# Media Components

Media components render images, icons, video, audio, and embedded frames. They handle responsive sizing, lazy loading, accessibility attributes, and security sandboxing. All accept the shared `props` bag (where most media attributes live) plus `visibility` and `responsive` modules; `$record.*` references resolve in `props.src`, `props.alt`, etc.

```yaml
components:
  - type: image
    props: { src: '$record.cover', alt: '$record.title', loading: lazy, objectFit: cover }
  - type: icon
    props: { name: check-circle, size: 20, color: 'var(--color-primary)' }
```

## `image`

A responsive image.

| Property          | Description                                    |
| ----------------- | ---------------------------------------------- |
| `props.src`       | Image URL (required; supports `$record.*`).    |
| `props.alt`       | Alternative text (required for accessibility). |
| `props.loading`   | `lazy` defers loading until near the viewport. |
| `props.srcset`    | Candidate sources for responsive selection.    |
| `props.sizes`     | Source-size hints paired with `srcset`.        |
| `props.width`     | Intrinsic width (prevents layout shift).       |
| `props.height`    | Intrinsic height.                              |
| `props.objectFit` | Scaling: `cover`, `contain`, `fill`, `none`.   |

A failed load shows a placeholder. Wrap an `image` in a [`link`](/en/docs/interactive-components#link) to make it clickable.

## `icon`

An inline SVG icon from the Lucide icon set.

| Property            | Description                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `props.name`        | Lucide icon name (maps to the matching SVG; supports `$variable`).                           |
| `props.size`        | Width/height in pixels (default: 24).                                                        |
| `props.color`       | SVG stroke color (defaults to `currentColor`; supports `$variable`).                         |
| `props.strokeWidth` | SVG stroke width (default: 2).                                                               |
| `props.className`   | Tailwind classes (e.g. color utilities).                                                     |
| `props.ariaLabel`   | Accessible label — sets `role="img"` and `aria-label`; without it the icon is `aria-hidden`. |

Icons render correctly as children of `button` and `link`, and emit `data-testid="icon-{name}"`.

## `video`

A video player supporting direct files and YouTube/Vimeo embeds.

| Property            | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| `props.src`         | Direct video URL or embed URL (YouTube/Vimeo auto-convert to an iframe). |
| `props.poster`      | Preview image shown before playback.                                     |
| `props.controls`    | Show playback controls.                                                  |
| `props.autoplay`    | Autoplay on load.                                                        |
| `props.muted`       | Start muted.                                                             |
| `props.loop`        | Loop playback.                                                           |
| `props.aspectRatio` | Responsive sizing (`16:9`, `4:3`, or custom).                            |
| `props.tracks`      | Subtitle/caption tracks (VTT format).                                    |

## `audio`

An audio player.

| Property         | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| `props.src`      | Audio URL (required for single-source audio).                  |
| `props.controls` | Show playback controls.                                        |
| `props.autoplay` | Autoplay on load.                                              |
| `props.loop`     | Loop playback.                                                 |
| `props.sources`  | Multiple formats with MIME types (for cross-browser fallback). |

## `iframe`

An embedded external frame.

| Property                                             | Description                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------ |
| `props.src`                                          | Frame URL (required).                                              |
| `props.title`                                        | Accessible title (required for accessibility).                     |
| `props.sandbox`                                      | Sandbox attribute restricting the frame's capabilities (security). |
| `props.allow`                                        | Permissions granted (e.g. camera, microphone).                     |
| `props.width` / `props.height` / `props.aspectRatio` | Responsive sizing.                                                 |

## `carousel`

A horizontally or vertically scrolling slideshow of child slides.

| Property            | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `children`          | Slide components.                                        |
| `props.orientation` | Scroll direction: `horizontal` or `vertical`.            |
| `props`             | Additional HTML attributes (e.g. autoplay/loop options). |

## `aspect-ratio`

A wrapper that maintains a fixed aspect ratio for its child (commonly a media element).

| Property      | Description                                  |
| ------------- | -------------------------------------------- |
| `props.ratio` | The aspect ratio to enforce (e.g. `16:9`).   |
| `children`    | The media (or other) component to constrain. |

## Related Pages

- [Pages Overview](/en/docs/pages-overview) — the component model and variable substitution.
- [Content Components](/en/docs/content-components) — text and prose blocks.
- [Layout Components](/en/docs/layout-components) — containers and grids for media layout.
- [SEO & Metadata](/en/docs/seo-meta) — Open Graph images and preload hints.
- [Buckets](/en/docs/buckets-overview) — storage for uploaded media referenced by `src`.