Image

Pictures without layout shift: placeholder, soft fade-in, fallback, a dark-mode source. Free, MIT · Data and metrics › Cards

A picture that reserves its box, shows a placeholder, fades in when it arrives (at once when cached) and falls back on error. A new src (or a mode switch with srcDark) keeps the old picture until the new one is ready and cross-fades. Rest props, className, style and ref go to the wrapper ui-image.

Installation

npx valyro-cli@latest add image

npx shadcn@latest add https://valyro.xyz/r/image.json

npm install valyro-ui

import 'valyro-ui/styles.css';
import { Image } from 'valyro-ui';

Props

Prop	Type	Default
`src` *	`string`		The picture. An empty string keeps the placeholder up (the address is still on its way).
`alt` *	`string`		Text alternative; `""` marks a decorative picture.
`srcDark`	`string`		Source for dark mode: follows the colour scheme of the nearest ThemeProvider / ThemeScope, cross-fading on a switch.
`srcSet`	`string`		Responsive candidates for `src` (not for `srcDark`).
`sizes`	`string`		Layout widths for `srcSet`.
`width`	`number`		Intrinsic width in px: with `height`, reserves the box before the picture arrives.
`height`	`number`		Intrinsic height in px.
`aspectRatio`	`number \| string`		Reserves the box before load so nothing below moves, e.g. `"16/9"` or `1.5`.
`fit`	`'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'`	`'cover'`	How the picture fills the reserved box (`object-fit`).
`placeholder`	`'shimmer' \| 'color' \| 'blur' \| 'none' \| ReactNode`	`'shimmer'`	What shows while loading: a moving sheen, a plain fill, a blurred preview (`blurDataURL`), nothing, or your node.
`blurDataURL`	`string`		A tiny data URL shown blurred while the picture loads (`placeholder="blur"`).
`fallback`	`ReactNode \| string`		Shown when the picture fails: a string is tried once as another source; a node is shown as is. Default: an image icon.
`priority`	`boolean`	`false`	Above the fold: loads eagerly at high priority and appears without a fade.
`loading`	`'lazy' \| 'eager'`		Native lazy loading (default `lazy`, `eager` with `priority`).
`crossOrigin`	`'anonymous' \| 'use-credentials' \| ''`		CORS mode of the request.
`referrerPolicy`	`ComponentPropsWithRef<'img'>['referrerPolicy']`		Referrer sent with the request.
`imgRef`	`Ref<HTMLImageElement>`		Ref to the `<img>` element on screen (`ref` is the wrapper's).
`onStatusChange`	`(status: ImageStatus) => void`		Called when the picture starts loading, appears or fails.
`labels`	`Partial<ImageLabels>`		Overrides for the built-in English text; keys left out keep their defaults.

Related components

Card — All-purpose cards
Item Card — Row card: icon, title, description and a control on the right
Record Card — Record card: status, context, key fields and actions
Carousel — Carousel: scroll snap, swipe, autoplay, thumbnails
Empty State — No-data screen
Data Table — Tables with search and sorting
Data Grid — Grid for 100,000 rows: grouping, filters, inline editing
Virtual List — Virtual list for 100,000 rows
Bulk Action Bar — Actions for selected rows, with keyboard shortcuts
List Block — List with images or icons, descriptions and values
Description List — Key–value list: stacked, inline or a grid with icons
Tree View — Tree structures

Previous: Record Card · Next: Carousel · All Data and metrics