Skip to Content

Video Section

Present accessible video stories, tutorials, playlists, and lightboxes with native browser controls.

VideoSection composes native HTML video with section layouts for product films, agency reels, testimonials, and tutorials. It does not host, transcode, or download media for you.

Beta API maturity: Beta. Media formats, captions, and licensing remain the application's responsibility.

Import

import { VideoSection, type VideoItem } from "@puzzle-ui/pieces";

Basic usage

Supply one or more sources for each video. preload defaults to none, so a poster or thumbnail is shown without fetching the video file before the viewer chooses to play it.

390 × 844

Variants

Each variant changes the presentation while preserving native playback, keyboard controls, captions, and app-owned video sources.

featured - Give one production video the main focus.

390 × 844

split - Pair the video with supporting editorial content.

390 × 844

background - Use a muted, inline video as a backdrop.

390 × 844

carousel - Browse a horizontal set of playable videos.

390 × 844

grid - Show several videos in a responsive collection.

390 × 844

playlist - Select a video from a keyboard-accessible playlist.

390 × 844

cinematic - Give a wide-format film more visual room.

390 × 844

browser - Frame a product walkthrough like an application window.

390 × 844

phone - Present vertical mobile footage.

390 × 844

testimonials - Pair customer video with a quote and speaker.

390 × 844

tutorial - Show instructional footage with captions.

390 × 844

lightbox - Open a selected video in an accessible dialog.

390 × 844
VariantUse case
featuredA single lead film.
splitVideo alongside supporting content.
backgroundMuted inline footage behind a section.
carouselA browsable video collection using the UI Carousel.
gridSeveral independent video cards.
playlistOne player with selectable items.
cinematicWide-format footage.
browserProduct demonstrations in a framed player.
phoneVertical mobile video.
testimonialsCustomer footage with quote and speaker.
tutorialInstructional video with captions.
lightboxA thumbnail opens an accessible UI Dialog.

Controls, autoplay, and captions

Native video controls are enabled by default. To enable autoplay, set both autoplay and muted; playback is still disabled when the browser requests reduced motion. The section always uses playsInline. Use loop only for content where repetition is appropriate.

Captions are supplied as WebVTT tracks:

captions={[
  {
    src: "/media/demo.en.vtt",
    srclang: "en",
    label: "English",
    default: true,
  },
]}

Set preload="metadata" only when metadata is needed before playback. The default preload="none" prevents unnecessary downloads. Use a responsive aspectRatio (16 / 9, 4 / 3, 1 / 1, or 9 / 16) and provide an appropriately cropped poster.

390 × 844

Composition and customization

VideoSection accepts the same section heading and action props as other Pieces sections. Use the children slot for transcripts, speaker bios, attribution, or links to a full recording. Keep media hosting and analytics in the application.

<VideoSection
  title="How the agency works"
  eyebrow="Field notes"
  variant="testimonials"
  videos={customerStories}
  actions={<Button variant="outline">Meet the team</Button>}
>
  <a href="/stories">Read all customer stories</a>
</VideoSection>

Accessibility and responsive behavior

  • Every player has a descriptive accessible name; accessibleLabel overrides the generated label for non-text titles.
  • Native controls support keyboard and touch input. The carousel uses the UI Carousel's navigation controls; the lightbox uses the UI Dialog's focus and Escape behavior.
  • Supply captions for spoken content and meaningful poster alternatives where the thumbnail communicates information.
  • Autoplay requires muted playback and is suppressed for reduced-motion preferences. There is no automatic video preload by default.
  • Players preserve the requested aspect ratio and adapt to the available width.

API

PropTypeRequiredDefaultDescription
videosreadonly VideoItem[]Yes—Video records to present. IDs must be unique.
variantVideoSectionVariantNofeaturedLayout variant.
featuredVideoIdstringNoFirst itemInitial featured/selected video ID.
selectedVideoIdstringNoUncontrolledControlled playlist selection.
onVideoSelect(id: string) => voidNo—Called when the selected video changes.
controlsbooleanNotrueShow browser-native playback controls.
autoplaybooleanNofalseRequest autoplay; it is applied only with muted and without reduced motion.
mutedbooleanNofalseMute audio. Required for autoplay.
loopbooleanNofalseLoop playback.
preload"none" | "metadata"No"none"Browser preload hint; auto is intentionally unavailable.
aspectRatio"16 / 9" | "4 / 3" | "1 / 1" | "9 / 16"No"16 / 9"Responsive media ratio.
childrenReactNodeNo—Additional transcript, attribution, or related content.

VideoItem contains id, title, sources, optional accessibleLabel, poster, thumbnail, duration, description, quote, actor, and captions. Each VideoSource has src and optional type; each VideoCaption has src, srclang, label, and optional default.

Theme support

The section consumes semantic variables from @puzzle-ui/theme and inherits active or scoped themes. Wrap the application with Theme, and use semantic roles such as text, surface, border, and primary for local overrides. Avoid hard-coded colors, spacing, radii, and shadows.

.brand-section {
  color: var(--puzzle-color-text);
  background: var(--puzzle-color-surface);
  border-color: var(--puzzle-color-border);
}

TypeScript example

The package exports this component from its root. Derive a wrapper's exact prop type from the public component rather than widening it:

import type { ComponentProps } from "react";
import { VideoSection } from "@puzzle-ui/pieces";

type VideoSectionProps = ComponentProps<typeof VideoSection>;

export function SectionWrapper(props: VideoSectionProps) {
  return <VideoSection {...props} />;
}

Framework compatibility

The section is router-independent. Static compositions can be server-rendered; place callback-driven interactions in the framework's client boundary. See Next.js and TanStack Start integration for runnable framework examples and SSR guidance.