Figure

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

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)',
})

Copy

With a held ratio

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

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' }),
)

Copy

Captioning something else

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

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.

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