# Figure

> An image and its caption, as one figure — with the space held before the image arrives.

A `<figure>` ties a caption to what it describes, which a paragraph under an image does not. Pass `src` for the common case, or children for anything else worth captioning.

## Basic figure

```javascript
figure({
  src: '/logo.svg',
  alt: 'The sitelo wordmark',
  caption: 'The wordmark, as it appears in the top bar.',
  style: '--su-figure-bg: var(--su-surface-2)',
})
```

## With a held ratio

`ratio` wraps the image in an `aspectRatio()`, so the caption never jumps down the page when the image loads.

```javascript
grid({ min: '13rem' },
  figure({ src: '/logo.svg', alt: '', ratio: '16 / 9', caption: 'ratio: 16 / 9' }),
  figure({ src: '/logo.svg', alt: '', ratio: '1 / 1', caption: 'ratio: 1 / 1' }),
)
```

## Captioning something else

Without `src`, the children are the figure’s content.

```javascript
figure({ caption: 'Table 1 — output of a default build.' },
  table({
    dense: true,
    columns: [{ key: 'file', header: 'File' }, { key: 'size', header: 'Size', align: 'end' }],
    rows: [
      { file: 'index.html', size: '4.1 kB' },
      { file: '404.html', size: '860 B' },
      { file: 'sitemap.xml', size: '155 B' },
    ],
  }),
)
```

## Code with a caption

Note the `text` prop on `code()`: children render as HTML everywhere in this library, so a sample containing tags needs escaping or the browser builds it instead of showing it.

```javascript
figure({ caption: 'The whole of a sitelo page.' },
  code({ text: 'export default () => "<h1>Hello</h1>"' }),
)
```

## Alt text

The `alt` attribute is always written, empty if you give nothing — an image with no `alt` at all is announced by its filename, which is worse than silence. A caption is not a substitute: the caption is read by everyone, the alt describes the image to someone who cannot see it.

When the caption already says everything the image does, `alt: ''` is the correct answer.

## In prose

Figures coming out of a Markdown renderer are styled by `prose()` already. This component is for figures you build yourself.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | — | Image source. Omit and use children instead. |
| `alt` | `string` | `''` | Alt text. Always written, even when empty. |
| `caption` | `Child` | — | The figcaption. |
| `ratio` | `string` | — | Holds the space before the image loads. |