Ballmac UI home

Video Dialog

A thumbnail with a play button that opens a video in a focus-trapped dialog, for a video file, an embed URL or a YouTube id from the privacy-friendly domain, mounting the player only while open.

Installation

$ pnpm dlx shadcn@latest add @ballmac/video-dialog

Usage

import { VideoDialog } from "@/components/ballmac/video-dialog"

The full example is in the Code tab above.

Examples

Shapes

API reference

PropTypeDefault
title*

Name of the video. Read by screen readers and used as the frame's title.

string—
src

A video file to play with the browser's own player.

string—
embedUrl

A page to embed instead, such as a Vimeo player URL.

string—
youtubeId

A YouTube video id. Plays from the privacy-friendly youtube-nocookie.com domain.

string—
thumbnail

Image shown on the button.

string—
thumbnailAlt

Describes the thumbnail for screen readers. Leave empty when the title already says it.

string""
duration

Length shown on the button, such as "2:41".

string—
aspect

Shape of the video frame.

"video" | "square" | "cinema""video"
open

Controlled open state.

boolean—
onOpenChange

Called when the dialog opens or closes.

(open: boolean) => void—
className

Classes for the thumbnail button.

string—

Also accepts the standard attributes of its root element.

Accessibility

KeyAction
Enter / SpaceOpens the video
EscapeCloses it and returns focus to the thumbnail
Screen readersButton reads 'Play video: Title'; the dialog is named by the title

Use with AI

<VideoDialog title thumbnail duration youtubeId | embedUrl | src aspect />. The player is created on open and removed on close, so nothing loads or keeps playing until asked. With the shadcn MCP server set up (guide), ask your agent:

Add the Ballmac UI Video Dialog (@ballmac/video-dialog) to this project with the shadcn MCP, then use it where it fits.

Use it for

  • Product demos and launch videos on landing pages
  • Tutorial thumbnails

Not for

  • Inline background video
  • Audio only (use an audio player)

Registry JSON: https://ui.ballmac.com/r/video-dialog.json

Credits

Free to use in personal and commercial projects.