Data

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.

Preview
01 Installation

Install

Pull Image from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line
import { Image } from "@brika/clay";
tsxGranular1 line
import { Image } from "@brika/clay/components/image";
02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxImage.tsx18 lines
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>
  );
}
03 Examples

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.

04 Accessibility

Accessibility

  • Always supply a meaningful alt text; use alt="" only for purely decorative images.
  • The skeleton overlay is aria-hidden so loading state does not pollute the AT tree.
  • The ImageFallback slot is aria-hidden by default; add an accessible label when the fallback content conveys meaningful information.
05 Tokens 4 theme-overridable

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
ColorFill, border, and text colors.3
  • --image-skeleton-colorcolorvar(--skeleton-pulse-color, var(--accent))
    components.image.skeletonColor

    Color 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.fallbackBg

    Background 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.fallbackIconColor

    Color of the default `ImageOff` icon shown when the source fails and no custom `fallback` is provided.

MotionAnimation duration and easing.1
  • --image-transition-durationduration300ms
    components.image.transitionDuration

    Duration 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.

jsonmy-theme.json12 lines
{
  "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.

06 API reference

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 ''
    string
    Alt text passed to the underlying <img>. Use "" for decorative images.
  • loadingdefault 'lazy'
    'lazy' | 'eager'
    Native loading attribute. Defaults to "lazy".
  • string
    URL of the image to load. Changing src resets the loader.
  • timeoutMsdefault 5000
    number
    Milliseconds before a stalled load is treated as an error. Prevents a hanging image host from blocking the fallback indefinitely.

<ImageContext />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.

<ImageFallback />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.