---
title: Image
description: Content image as a figure with alt text, lazy loading, and a CLS-safe ratio box
visibility: guest
draft: false
---

# 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>`](/components/avatar); for a
before/after slider use [`<x-wirekit::image-compare>`](/components/image-compare).

## Usage

:::preview{title="Content image with a caption"}
<x-wirekit::image
    src="/placeholder/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):

:::preview{title="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
/>
:::

## Square, contain

:::preview{title="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:

:::preview{title="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. |
| `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.