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/480x300?bg=fbcfe8&fg=9d174d&label=Photo&gradient=none"
    alt="The team gathered at the 2026 offsite"
    width="480"
    height="300"
    loading="eager"
    caption="The 2026 offsite"
    rounded
/>

width and height are the image's own size in pixels. The browser reserves its box from them before the file arrives, so the caption and the text after it do not move when the image loads.

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/480x270?bg=bfdbfe&fg=1e40af&label=16:9&gradient=none"
    alt="A wide landscape"
    ratio="16/9"
    fit="cover"
    rounded
/>

Responsive sources and a reserved box

srcset and sizes go on the image itself, so the browser picks the smallest file that fills the space. width and height give the image's own size in pixels: the browser reserves the box from their ratio before the file arrives, which keeps a layout without ratio from shifting. fetchpriority="high" with loading="eager" suits the image a page shows first.

Two sources, reserved box

<x-wirekit::image
    src="/placeholder/480x270?bg=e9d5ff&fg=5b21b6&label=480w&gradient=none"
    srcset="/placeholder/480x270?bg=e9d5ff&fg=5b21b6&label=480w&gradient=none 480w, /placeholder/960x540?bg=e9d5ff&fg=5b21b6&label=960w&gradient=none 960w"
    sizes="(min-width: 40rem) 480px, 100vw"
    width="480"
    height="270"
    alt="A wide landscape in two resolutions"
    rounded
/>

Art direction

srcset picks the same picture in another resolution. A different crop for a different width, a portrait hero on a phone and a landscape one on a desk, takes sources: each entry is a file for a media condition, rendered as a <source> in a <picture> before the image, and the browser loads the first that matches and else src, never two. Give each source its own width and height and leave ratio unset: the browser reserves the box from the source it chose before the file arrives, so neither crop moves the page as it loads.

Portrait on a phone, landscape on a desk

A storefront hero, cropped for the width it is shown at

<x-wirekit::image
    src="/placeholder/1600x900?bg=bae6fd&fg=075985&label=Desk+1600x900&gradient=none"
    width="1600"
    height="900"
    :sources="[
        ['media' => '(width <= 40rem)', 'srcset' => '/placeholder/640x800?bg=fbcfe8&fg=9d174d&label=Phone+640x800&gradient=none', 'width' => 640, 'height' => 800],
    ]"
    alt="A storefront hero, cropped for the width it is shown at"
    loading="eager"
    fetchpriority="high"
    rounded
/>

A hero that loads first also gets a preload in the page's <head>, one per source, each with the media condition its source answers, so the browser fetches exactly the file it will show. The conditions must not overlap, or it preloads two:

<link rel="preload" as="image" href="/hero-tall-640.jpg" imagesrcset="/hero-tall-640.jpg 640w, /hero-tall-1280.jpg 1280w" imagesizes="100vw" media="(width <= 40rem)" fetchpriority="high">
<link rel="preload" as="image" href="/hero-wide-1600.jpg" imagesrcset="/hero-wide-1600.jpg 1600w, /hero-wide-3200.jpg 3200w" imagesizes="100vw" media="(width > 40rem)" fetchpriority="high">

type serves a newer format to the browsers that read it: a source with 'type' => 'image/avif' and no media comes before the image, and a browser without AVIF takes the next.

Square, contain

Square 1/1, contain

<x-wirekit::image
    src="/placeholder/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/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.
`srcset`	`string\|null`	`null`	Responsive sources, written on the `<img>`.
`sizes`	`string\|null`	`null`	The width the image takes in the layout, for `srcset`, written on the `<img>`.
`width`	`int\|string\|null`	`null`	Intrinsic width in pixels, written on the `<img>`; with `height` it reserves the box before load.
`height`	`int\|string\|null`	`null`	Intrinsic height in pixels, written on the `<img>`.
`fetchpriority`	`string\|null`	`null`	`high`, `low` or `auto` on the `<img>`; `null` leaves it to the browser.
`sources`	`array`	`[]`	Art direction: a file per media condition, each `['srcset' => …]` with `media`, `sizes`, `type`, `width` and `height` as it needs them, rendered as `<source>` elements in a `<picture>` — see Art direction.
`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.

Image

Was this page helpful?