Media

Video embed

Embeds video with a preview, playback controls, captions, and transcript access.

implementedReference catalogvideo or iframeAspectRatio + Semantics + platform media controller

Overview

Embeds video with a preview, playback controls, captions, and transcript access. Its semantic foundation is Labelled media region with iframe or native video. Source scope: Reference catalog.

This element owns a standalone primitive contract and does not depend on a product-specific component.

Visual Example

Video titleCaptions available

When to Use

Use Video embed when its semantic purpose matches the user task. Prefer native platform behavior, concise labels, predictable placement, and content that remains understandable without visual styling.

Do

Use the canonical element ID and semantic role.
Keep labels and state programmatically available.
Test the element with real content and every supported input modality.

Don't

Do not substitute a visually similar element with different semantics.
Do not add focusable descendants without a documented keyboard model.
Do not communicate state through color or motion alone.

Anatomy

1Poster or media

2Playback controls

3Captions or transcript

4Status

Variants

inlinecontainedfull-width

Variants preserve the same semantics and accessible name. Density changes never reduce the minimum interactive target.

States

idleloadingplayingpausedendederror

Focus-visible takes precedence over hover and selected styling. Loading and disabled behavior never silently remove essential information or recovery paths.

Behavior

All media controls are operable by keyboard and retain visible focus. Web targets are at least 44 × 44 CSS pixels and Flutter targets are at least 48 × 48 dp.

Accessibility

Labelled media region with iframe or native video. The element exposes an accessible name, role, state, value, and result where applicable; retains visible 3:1 focus indication; supports 200% text scaling and 320 CSS pixel reflow; and preserves structure in forced-colors and reduced-motion modes.

Tokens

color.* semantic roles→native semantic composition→video or iframe

Spacing, sizing, typography, border, radius, icon, motion, focus, and color decisions resolve from canonical tokens. Element code does not contain arbitrary visual literals.

Web and Flutter API

Web

<video or iframe>Video embed</video>

Flutter

AspectRatio + Semantics + platform media controller(/* semantic content */)

ds-video-embed is a registry identifier only; this library does not register an autonomous custom element under that name. Use the mapped component or native semantic composition shown above.

When an element includes an icon, use the exact Tabler name and semantic size from Foundations · Iconography.

Status

implemented. The contract is registered, visually represented, and included in automated documentation and accessibility validation. This status describes contract coverage, not independent production certification.