Image

A figure-based image component with fallback, lightbox preview, aspect ratio control, and caption. Built on <figure>, <dialog>, and native CSS.

Component Skill — components/image/component-skill.md

Native basis

<figure> wrapping <img> with optional <figcaption>. Uses <dialog> for fullscreen lightbox.

Web Platform APIs

<figure> <dialog> aspect-ratio @starting-style

Classes

.image .image-caption .image-fallback .image-lightbox

Data attributes

• data-preview — enables click-to-preview lightbox

• data-ratio — values: 1/1, 4/3, 3/2, 16/9, 21/9, 3/4

• data-fit — values: contain, fill, none

• data-radius — values: none, sm, md, full

Default

Basic image in a figure with rounded corners and cover fit.

<figure class="image">
  <img src="photo.jpg" alt="Description" />
</figure>

With Caption

Semantic <figcaption> for descriptive text below the image.

<figure class="image">
  <img src="photo.jpg" alt="Description" />
  <figcaption class="image-caption">Caption text</figcaption>
</figure>

Fallback

Shows a placeholder when the image fails to load. Uses :has() to detect error state.

<figure class="image">
  <img src="photo.jpg" alt="Description" />
  <div class="image-fallback">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
      <rect width="18" height="18" x="3" y="3" rx="2" ry="2"/>
      <circle cx="9" cy="9" r="2"/>
      <path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21"/>
    </svg>
  </div>
</figure>

Lightbox Preview

Click the image to open a fullscreen preview with zoom and rotate controls. Uses native <dialog>.

<figure class="image" data-preview>
  <img src="photo.jpg" alt="Description" />
</figure>

Aspect Ratios

Controlled aspect ratios via data-ratio.

<figure class="image" data-ratio="1/1">...</figure>
<figure class="image" data-ratio="4/3">...</figure>
<figure class="image" data-ratio="16/9">...</figure>
<figure class="image" data-ratio="3/4">...</figure>

Object Fit

Control how the image fills its container via data-fit.

<!-- default: cover -->
<figure class="image" data-ratio="4/3">...</figure>

<!-- contain -->
<figure class="image" data-ratio="4/3" data-fit="contain">...</figure>

<!-- none (natural size, clipped) -->
<figure class="image" data-ratio="4/3" data-fit="none">...</figure>

Border Radius

Control border radius via data-radius.

<figure class="image" data-radius="none">...</figure>
<figure class="image" data-radius="sm">...</figure>
<figure class="image">...</figure>  <!-- default: lg -->
<figure class="image" data-radius="full">...</figure>

CSS view file

Styles for figure, caption, fallback, and lightbox dialog.

JavaScript view file

Fallback error detection and lightbox preview with zoom/rotate.