Image
An <img> that never writes an inline style, so it renders under a strict CSP (§19.3).
Import
import { Image } from '@nizivo/react/image';
// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css
import '@nizivo/react/css/image.css';Static or interactive
Server. It ships no client JavaScript when a Server Component renders it, in every Next.js build
mode; its code is bundled only when a client component (a 'use client' file) imports it. How to
choose.
In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.
Examples
Basic
Source only
import type { ComponentPropsWithRef, JSX } from 'react';
import { Image } from '@nizivo/react/image';
/** Stands in for a framework image component (Next `Image`, unpic). */
function FrameworkImage({ alt, ...props }: ComponentPropsWithRef<'img'>): JSX.Element {
return <img alt={alt} {...props} />;
}
export function ImageExample(): JSX.Element {
return (
<div>
<Image
src="/media/mug.jpg"
alt="Stoneware mug in sage glaze"
width={800}
height={1000}
ratio="4/5"
/>
<Image src="/media/hero.jpg" alt="" width={1600} height={900} ratio="16/9" priority />
<Image
src="/media/napkins.jpg"
alt="Linen napkins, folded"
width={600}
height={600}
render={<FrameworkImage />}
/>
</div>
);
}
Props
An <img> that never writes an inline style, so it renders under a strict CSP (§19.3).
Server component Renders data-slot="image" with the class nz-image. Props: ImageProps. Source: src/image/image.tsx.
| Name | Type | Default | Description |
|---|---|---|---|
altrequired | string | – | Required. |
heightrequired | number | – | |
priority | boolean | false | An above-the-fold image: eager loading and |
ratio | ImageRatio"1/1""4/5""3/2""16/9" | – | |
render | RenderProp<ImageState> | – | A framework image component, for example |
srcrequired | string | – | |
widthrequired | number | – | Intrinsic width in px. Required with |
- Also takes every attribute of
<img>exceptalt,children,height,src,width. (Omit<ComponentPropsWithRef<"img">, "src" | "alt" | "width" | "height" | "children">)
render takes an element, or, in client code, a function of the props and this state (ImageState):
| Name | Type | Default | Description |
|---|---|---|---|
priorityrequired | boolean | – | |
ratiorequired | ImageRatio | undefined"1/1""4/5""3/2""16/9" | – |
Other exports
ImagePropstypeimport type { ImageProps } from '@nizivo/react/image'The props of
Image, listed above.ImageRatiotypeimport type { ImageRatio } from '@nizivo/react/image'Aspect-ratio presets, emitted as
data-ratioand cropped withobject-fit(§14.3).type ImageRatio = "1/1" | "4/5" | "3/2" | "16/9"ImageStatetypeimport type { ImageState } from '@nizivo/react/image'The render state of
Image, listed above.
Data attributes and slots
Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.
| Slot | Rendered by | Data attributes |
|---|---|---|
image.nz-image | Imageroot (takes render) |
|
CSS hooks
Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.
| Hook | Default | Read as |
|---|---|---|
--nz-image-fit | cover |
|
--nz-image-radius | --nz-radius-none |
|
Layers: nz.components. Classes: .nz-image.
Tokens this stylesheet reads (1)
--nz-radius-none
Accessibility
Nothing in this component takes focus or keyboard input.
Keyboard
None.
Figma
Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.
- Canonical: none
- Ghost masters: none