Image

<x-wirekit::image> renders a user-content image as a semantic <figure> with required alt text, native lazy loading, and an optional caption. Set a ratio and it reserves the space before the image loads, so the page never shifts as images arrive (CLS-safe). The component only renders — pass a ready URL (a signed, ACL-protected download URL works unchanged).

For a profile picture use <x-wirekit::avatar>; for a before/after slider use <x-wirekit::image-compare>.

Usage

Content image with a caption

The team gathered at the 2026 offsite — The 2026 offsite

<x-wirekit::image
    src="/placeholder/1c608019/480x300?bg=fbcfe8&fg=9d174d&label=Photo&gradient=none"
    alt="The team gathered at the 2026 offsite"
    caption="The 2026 offsite"
    rounded
/>

CLS-safe ratio box

Set ratio so the box is sized from the start and the layout never jumps. fit controls how the image fills the box — cover (fill + crop) or contain (letterbox):

Fixed 16/9, cover

<x-wirekit::image
    src="/placeholder/1c608019/480x270?bg=bfdbfe&fg=1e40af&label=16:9&gradient=none"
    alt="A wide landscape"
    ratio="16/9"
    fit="cover"
    rounded
/>

Square, contain

Square 1/1, contain

<x-wirekit::image
    src="/placeholder/1c608019/300x300?bg=bbf7d0&fg=065f46&label=1:1&gradient=none"
    alt="A product shot"
    ratio="1/1"
    fit="contain"
    rounded
/>

Decorative image

An image that adds no information passes an empty alt so screen readers skip it. Only use this when the image is truly decorative:

Decorative image (empty alt)

<x-wirekit::image
    src="/placeholder/1c608019/480x160?bg=fde68a&fg=92400e&label=decorative&gradient=none"
    alt=""
    ratio="3/1"
    rounded
/>

Props

Prop	Type	Default	Description
`src`	`string\|null`	`null`	Image URL (ready-to-render; signed URLs work).
`alt`	`string`	`''`	Accessible name. Required for content images; empty for decorative.
`caption`	`string\|null`	`null`	Optional visible caption, rendered as a `<figcaption>`.
`ratio`	`string\|null`	`null`	Intrinsic aspect-ratio (`16/9`, `4/3`, `1/1`, …) — reserves space before load.
`fit`	`string`	`'cover'`	`cover` (fill + crop) or `contain` (letterbox). Applies only with a `ratio`.
`rounded`	`bool`	`false`	Round the corners with the `--radius-wk-md` token.
`loading`	`string`	`'lazy'`	Native `loading` — use `eager` for an above-the-fold hero.
`scope`	`string\|null`	`null`	Scoped personalization key.

Accessibility

alt is required for content images. Describe what the image shows. Pass alt="" only for a purely decorative image, so assistive tech skips it instead of announcing the file.
The image is wrapped in a <figure>; a caption renders as its <figcaption>.
With a ratio, the reserved box prevents layout shift, which also keeps focus order stable as images load.

Keyboard Interaction

This component is purely presentational and does not respond to keyboard input.

Was this page helpful?

Thanks — that helps.

Voting requires cookies or local storage. What we store