Skip to main content
View as Markdown

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.

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 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.

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.