Image
Compound image component with a skeleton pulse while loading and an ImageFallback slot rendered when the source fails, times out, or is absent. A hanging image host still shows the fallback once timeoutMs elapses.
Install
Pull Image from the barrel for everyday use, or the granular path when you want a tighter bundle.
import { Image } from "@brika/clay";import { Image } from "@brika/clay/components/image";A minimal example
Drop this into a page. Native HTML attributes pass through to the underlying primitive.
import { ImageOff } from 'lucide-react';
import { Image, ImageFallback } from '@brika/clay/components/image';
import { SAMPLE_A } from './images';
/**
* A real photo loaded from a picsum URL, with a skeleton pulse while loading and an `ImageFallback` icon shown if the source fails.
*/
export default function ImageDefaultDemo() {
return (
<div className="h-40 w-64 overflow-hidden rounded-lg">
<Image src={SAMPLE_A} alt="A landscape photo" className="size-full">
<ImageFallback>
<ImageOff className="size-6" />
</ImageFallback>
</Image>
</div>
);
}Image, every way
Fallback
A deliberately broken src triggers the `ImageFallback` slot, showing the broken-image icon in place of the photo.
Transition
A button swaps between two real picsum photos, triggering the A-to-B crossfade where the previous photo stays visible at full opacity until the new one fades in completely.
Accessibility
- Always supply a meaningful
alttext; usealt=""only for purely decorative images. - The skeleton overlay is
aria-hiddenso loading state does not pollute the AT tree. - The
ImageFallbackslot isaria-hiddenby default; add an accessible label when the fallback content conveys meaningful information.
Theme tokens
Every CSS variable Image reads, with its default and the
dotted path you'd write in a ThemeConfig JSON
to override it. Set any of these in your theme to retune Image
without touching component code.
Image tokens
4 tokens--image-skeleton-colorcolorvar(--skeleton-pulse-color, var(--accent))components.image.skeletonColorColor of the animated skeleton pulse shown while the image loads. Falls back to `--skeleton-pulse-color` so the Image skeleton always matches any standalone Skeleton components in the same theme.
--image-fallback-bgcolorvar(--muted)components.image.fallbackBgBackground of the container while the image is loading or has errored. Keeps the layout stable and provides a neutral backdrop for the fallback icon.
--image-fallback-icon-colorcolorvar(--muted-foreground)components.image.fallbackIconColorColor of the default `ImageOff` icon shown when the source fails and no custom `fallback` is provided.
--image-transition-durationduration300mscomponents.image.transitionDurationDuration of the fade-in transition when an image finishes loading and of the crossfade when the `src` changes. Set to `0ms` to disable animation.
Override in a theme
Authoring a theme is plain JSON. Drop overrides under
components.image, the names
are camelCase versions of the variable suffix.
{
"id": "my-theme",
"name": "My Theme",
"description": "...",
"accentSwatches": ["#000"],
"components": {
"image": {
"skeletonColor": "var(--skeleton-pulse-color, var(--accent))"
}
}
}
Then apply with applyTheme(myTheme)
(see the theming guide),
scope it to a subtree with themeToCssVars(myTheme, mode),
or consume any token directly in your own JSX with the matching Tailwind utility
(e.g. bg-image-…) — see the
chips on each token row.
API reference
Props specific to Image. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.
<Image />
4 props- altdefault
''stringAlt text passed to the underlying<img>. Use""for decorative images. - loadingdefault
'lazy''lazy' | 'eager'Nativeloadingattribute. Defaults to"lazy". - stringURL of the image to load. Changing
srcresets the loader. - timeoutMsdefault
5000numberMilliseconds before a stalled load is treated as an error. Prevents a hanging image host from blocking the fallback indefinitely.
<ImageContext />
passthroughNo wrapper-specific props, all attributes pass through to the underlying primitive.
<ImageFallback />
passthroughNo wrapper-specific props, all attributes pass through to the underlying primitive.