Hero Video
Poster with a round play button over it; the whole frame plays and pauses.
$npx shadcn@latest add https://framebrick.co/r/hero-video.jsonFrom the Findit template, see it in context.
The file is only fetched when you press play; the poster is all that loads before.
import { HeroVideo } from "@/components/ui/hero-video";
// Clip from Pexels (Pexels License) and still from Unsplash (Unsplash License), both served by this site, so the
// page loads nothing from another host — before the click or after it.
export default function HeroVideoDemo() {
return (
<div className="flex w-full max-w-lg flex-col gap-3">
<HeroVideo src="/video/pexels-10959786.mp4" poster="/demo/hero-video-poster.webp" label="Play the clip" />
<p className="text-center text-xs text-muted-foreground">
The file is only fetched when you press play; the poster is all that loads before.
</p>
</div>
);
}Examples
In view
No button: the clip plays while it is on screen and stops when it leaves; with reduced motion it stays on its poster.
import { HeroVideo } from "@/components/ui/hero-video";
// Clip from Pexels (Pexels License) and still from Unsplash (Unsplash License), both served by this site.
/* No button: the clip plays while it is on screen and stops when it leaves; with reduced motion it stays on its poster. */
export default function HeroVideoViewDemo() {
return (
<div className="w-full max-w-lg">
<HeroVideo autoplay="view" src="/video/pexels-10959786.mp4" poster="/demo/hero-video-poster.webp" label="A look around the house" />
</div>
);
}<HeroVideo autoplay="view" src="/clinic.mp4" poster="/clinic.jpg" label="A look around the clinic" />Pill
A pill with the label in it instead of the round button; it fades while the video plays.
import { HeroVideo } from "@/components/ui/hero-video";
// Clip from Pexels (Pexels License) and still from Unsplash (Unsplash License), both served by this site.
// A pill with the label in it: press it to play and it fades; press the video to pause and it comes back.
export default function HeroVideoPillDemo() {
return (
<div className="w-full max-w-lg">
<HeroVideo src="/video/pexels-10959786.mp4" poster="/demo/hero-video-poster.webp" label="Watch a review" play="pill" caption="Watch a review" />
</div>
);
}<HeroVideo src="/review.mp4" poster="/review.jpg" label="Watch a review" caption="Watch a review" play="pill" />Caption, veil and stop button
A caption beside the button on hover, a veil on the poster, and a stop square while it plays.
import { HeroVideo } from "@/components/ui/hero-video";
// Clip from Pexels (Pexels License) and still from Unsplash (Unsplash License), both served by this site.
// Point at the card: a caption comes beside the button; press play: the veil goes; point at it again to stop.
export default function HeroVideoCaptionDemo() {
return (
<div className="w-full max-w-lg">
<HeroVideo
src="/video/pexels-10959786.mp4"
poster="/demo/hero-video-poster.webp"
label="Watch our activity"
caption="Watch our activity"
veil
stopButton
/>
</div>
);
}<HeroVideo
src="/activity.mp4"
poster="/activity.jpg"
label="Watch our activity"
caption="Watch our activity"
veil
stopButton
/>Installation
$ npx shadcn@latest add https://framebrick.co/r/hero-video.json1. Install the dependencies.
npm install motion clsx tailwind-merge2. Add
cn()tolib/utils.ts(skip if shadcn already created it).import { clsx, type ClassValue } from "clsx"; import { extendTailwindMerge } from "tailwind-merge"; /* tailwind-merge must know the site's type scale (globals.css) is a font size, not a text color — otherwise cn("text-h6 text-muted-foreground") drops text-h6. */ const twMerge = extendTailwindMerge({ extend: { classGroups: { "font-size": [{ text: ["display", "h1", "h2", "h3", "h4", "h5", "h6"] }] } }, }); export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }3. Copy the component into
components/ui/hero-video.tsx."use client"; import * as React from "react"; import { motion, type Transition } from "motion/react"; import { cn } from "@/lib/utils"; /* * Hero Video — a poster with a round play button over it; the whole frame is the control (from the Findit * "Card/Hero Video"). The button sits at 75% and comes to full on hover, with Framer's soft spring * (bounce 0, 0.4s). Nothing of the video is downloaded until someone presses play (preload="none"). * * Improvement over Framer: the button follows the video rather than the click, so it comes back when the video ends * or is paused from anywhere else, and the frame is a real button — keyboard and screen readers reach it. * * Three options come from the Semono "Card/Video", where every part moves on spring B (bounce 0.2, 0.4s): * caption a short line beside the button while the pointer — or keyboard focus — is over the card and the video is * not playing; it appears at once and the button slides left to keep the pair centred (half the caption's * width plus 10px); over the button itself it grows to 1.2; * veil a 25% black layer on the poster that fades away when the video plays and comes back when it pauses; * stopButton while the video plays the button returns as a stop square, but only while the pointer or focus is over * the card. Touch has no hover: a tap plays and a tap pauses, and the stop square never shows. * Without them it is as it was. The look stays the library's (a 48px translucent button), not Semono's white one. * The states are kept here, not handed down through Motion's hover variants: a variant would also reach the button when * the pointer is only over the card, and the growth is for the button itself. * * `play="pill"` is the Balancee testimonial card (VideoPlayer, mode "click"): instead of the round button, a pill with its own light * background and a 4px corner in the middle of the poster, saying `caption` (or `label`). A click plays the video and the pill fades * out; a click on the video pauses it and the pill fades back, following the video's own events like the button does. No growth, * no slide and no stop square: caption and stopButton are the pill's text and nothing. The pill has its own background * (bg-background text-foreground), so its contrast does not depend on the poster. The fade is opacity, which MotionConfig does * not skip, and that is right. * * `autoplay="view"` is the KorDent call-to-action video: a muted, looping clip with no button, played only while it is on screen * (an IntersectionObserver plays it when a tenth of it shows and pauses it when it leaves) and standing on its poster for a visitor * who asked for reduced motion (read from matchMedia in an effect, so the markup never depends on it). It is decoration: the frame * is an image named by `label`, the video inside is aria-hidden, and it is always muted. preload is "metadata", not "none" as with * the button, because it starts by itself and its first frame should be ready; the poster shows until it plays. * Reduced motion: the slide and the growth are transforms, which MotionConfig reducedMotion="user" skips; the fades stay. */ const soft: Transition = { type: "spring", bounce: 0, duration: 0.4 }; const bouncy: Transition = { type: "spring", bounce: 0.2, duration: 0.4 }; export type HeroVideoProps = { /** "view": no button; a muted loop that plays while it is on screen and stands on its poster with reduced motion. Left out: the poster and a play button, as it was. */ autoplay?: "view"; src: string; /** "circle" (default) is the round button; "pill" is a pill with the caption (or the label) in it, which fades while the video plays. */ play?: "circle" | "pill"; /** Shown before play and while paused. */ poster: string; /** What the button does, e.g. "Play the tour of 14 Almond Street". */ label: string; /** A short line beside the button while the card is hovered or focused and the video is not playing. */ caption?: string; /** A 25% black layer on the poster that fades away while the video plays. */ veil?: boolean; /** Bring the button back as a stop square while the video plays and the card is hovered or focused. */ stopButton?: boolean; loop?: boolean; /** Videos start muted so a browser lets them play; turn this off for sound. */ muted?: boolean; className?: string; }; function ViewVideo({ src, poster, label, loop = true, className }: Pick<HeroVideoProps, "src" | "poster" | "label" | "loop" | "className">) { const frame = React.useRef<HTMLDivElement>(null); const video = React.useRef<HTMLVideoElement>(null); /* Play while a tenth of it is on screen, pause when it leaves; never for a visitor who asked for reduced motion. */ React.useEffect(() => { const element = video.current; const box = frame.current; if (!element || !box || window.matchMedia("(prefers-reduced-motion: reduce)").matches) return; const observer = new IntersectionObserver( ([entry]) => { if (entry.isIntersecting) void element.play().catch(() => {}); else element.pause(); }, { threshold: 0.1 }, ); observer.observe(box); return () => { observer.disconnect(); element.pause(); }; }, []); return ( <div ref={frame} role="img" aria-label={label} className={cn("relative aspect-video w-full overflow-hidden rounded-lg bg-muted", className)}> <video ref={video} src={src} poster={poster} muted loop={loop} playsInline preload="metadata" aria-hidden className="absolute inset-0 size-full object-cover" /> </div> ); } export function HeroVideo(props: HeroVideoProps) { if (props.autoplay === "view") return <ViewVideo {...props} />; return <ClickVideo {...props} />; } function ClickVideo({ src, poster, label, play = "circle", caption, veil = false, stopButton = false, loop = true, muted = true, className }: HeroVideoProps) { const video = React.useRef<HTMLVideoElement>(null); const [playing, setPlaying] = React.useState(false); const [hovered, setHovered] = React.useState(false); const [focused, setFocused] = React.useState(false); const [focusVisible, setFocusVisible] = React.useState(false); const [onButton, setOnButton] = React.useState(false); const over = hovered || focusVisible; const pill = play === "pill"; const showButton = !playing || (stopButton && over); const showCaption = !pill && Boolean(caption) && !playing && over; const grows = !pill && (Boolean(caption) || stopButton); function toggle() { const element = video.current; if (!element) return; if (element.paused) void element.play().catch(() => setPlaying(false)); else element.pause(); } return ( <button type="button" onClick={toggle} aria-label={label} aria-pressed={playing} onPointerEnter={(event) => event.pointerType !== "touch" && setHovered(true)} onPointerLeave={() => setHovered(false)} onFocus={(event) => { setFocused(true); setFocusVisible(event.currentTarget.matches(":focus-visible")); }} onBlur={() => { setFocused(false); setFocusVisible(false); }} className={cn( "relative block aspect-video w-full cursor-pointer overflow-hidden rounded-lg bg-muted outline-none", "focus-visible:ring-[3px] focus-visible:ring-ring/50", className, )} > <video ref={video} src={src} poster={poster} muted={muted} loop={loop} playsInline preload="none" onPlay={() => setPlaying(true)} onPause={() => setPlaying(false)} onEnded={() => setPlaying(false)} className="absolute inset-0 size-full object-cover" /> {veil && ( <motion.span aria-hidden initial={false} animate={{ opacity: playing ? 0 : 1 }} transition={bouncy} className="pointer-events-none absolute inset-0 bg-black/25" /> )} {/* The button and the caption are a pair, centred together: when the caption comes, the button slides to make room. */} <span aria-hidden className="absolute inset-0 flex items-center justify-center gap-5"> {pill && ( <motion.span initial={false} animate={{ opacity: playing ? 0 : 1 }} transition={soft} className="rounded-sm bg-background px-4 py-2 text-sm font-medium whitespace-nowrap text-foreground shadow-xs" > {caption ?? label} </motion.span> )} {!pill && showButton && ( <motion.span layout={Boolean(caption)} initial={false} animate={{ opacity: hovered || focused ? 1 : 0.75, scale: grows && onButton ? 1.2 : 1 }} transition={grows ? bouncy : soft} onPointerEnter={(event) => event.pointerType !== "touch" && setOnButton(true)} onPointerLeave={() => setOnButton(false)} className="flex size-12 items-center justify-center rounded-full bg-black/25 text-white backdrop-blur-md" > {playing ? ( <svg aria-hidden viewBox="0 0 24 24" fill="currentColor" className="size-6"> <rect x="7" y="7" width="10" height="10" rx="1.5" /> </svg> ) : ( <svg aria-hidden viewBox="0 0 24 24" fill="currentColor" className="size-6 translate-x-px"> <path d="M8 5.5v13l11-6.5z" /> </svg> )} </motion.span> )} {showCaption && <span className="text-sm font-medium whitespace-nowrap text-white drop-shadow-sm">{caption}</span>} </span> </button> ); }
Usage
import { HeroVideo } from "@/components/ui/hero-video";
<HeroVideo src="/tour.mp4" poster="/tour.jpg" label="Play the tour of 14 Almond Street" />
// Semono's video card: a caption beside the button, a veil on the poster, a stop square while it plays
<HeroVideo src="/activity.mp4" poster="/activity.jpg" label="Watch our activity" caption="Watch our activity" veil stopButton />Props
| Prop | Type | Default | Description |
|---|---|---|---|
| src | string | — | The video file. |
| poster | string | — | Shown before play and while paused. |
| label | string | — | What the button does, e.g. "Play the tour of 14 Almond Street". |
| autoplay | "view" | — | view: no button; a muted loop that plays while it is on screen (a tenth showing) and pauses when it leaves, standing on its poster with reduced motion (KorDent). The frame is an image named by label and the video is aria-hidden; preload is metadata. Left out: the poster and a play button. |
| play | "circle" | "pill" | "circle" | The round button, or a pill with the caption (falling back to the label) in it, with its own light background, that fades while the video plays and comes back on pause (Balancee). With the pill, caption is its text and stopButton does nothing; label must say what the pill says. |
| caption | string | — | A short line beside the button while the pointer or keyboard focus is over the card and the video is not playing. The button slides left to keep the pair centred, and grows to 1.2 under the pointer. |
| veil | boolean | false | A 25% black layer on the poster that fades away when the video plays and comes back when it pauses. |
| stopButton | boolean | false | While the video plays, bring the button back as a stop square, but only while the pointer or focus is over the card. |
| loop | boolean | true | Start again when it ends. |
| muted | boolean | true | Videos start muted so a browser lets them play; turn it off for sound. |
- autoplay="view" is KorDent's call-to-action video at the end of nearly every page (a 1140 : 601 clinic clip, muted, looping, played only while it is on screen, still for reduced motion, with no button). An IntersectionObserver plays it when a tenth of it shows and pauses it when it leaves; reduced motion is read from matchMedia in an effect, so the markup never depends on it. It is decoration: the frame is an image named by label and the video inside is aria-hidden, always muted. preload is metadata rather than none, since it starts by itself and its first frame should be ready; the poster shows until it plays. The click-to-play video is unchanged. Blocks' about-video and media-band write their own and need not move.
- Nothing of the video is downloaded until someone presses play (preload="none") — only the poster.
- The button follows the video, not the click, so it comes back when the video ends or is paused from anywhere else.
- The whole frame is a button with aria-pressed, so a keyboard reaches it and the state is announced.
- The caption, veil and stop button are Semono's, where every part moves on a spring with a little bounce (0.2, 0.4 s). The look stays the library's: a 48 px translucent button, not Semono's white one. Without the options nothing changes.
- Touch has no hover: a tap plays and a tap pauses, and the stop square never shows. The caption is visual only; make `label` say the same thing so the accessible name matches what is seen.
- The slide and the growth are transforms, which <MotionConfig reducedMotion="user"> skips; the fades stay.
- It renders a plain <video> with no <track>, so axe lists "video-caption" as a manual check. That is right for a muted clip that only decorates the page; a video with speech needs captions, which this component has no slot for — use a player that has one.
AI prompt
Paste into v0, Lovable, Bolt or Claude to rebuild this component in your own project.
Create a React + Tailwind CSS + Motion (motion/react) component called HeroVideo. - The whole frame is a button (aspect-video, rounded-lg, overflow-hidden, bg-muted, visible focus ring) holding a <video> with a poster, muted, loop, playsInline and preload="none", filling it with object-cover. - A click plays or pauses. Keep a "playing" state from the video's own play, pause and ended events, not from the click. - While paused, a 48px circle sits in the middle: bg-black/25 with backdrop-blur-md and a white play triangle. It rests at opacity 0.75 and goes to 1 on hover and on keyboard focus, with a spring (bounce 0, duration 0.4s). - Accessibility: aria-label describing what plays, aria-pressed for the state. - Options, all off by default: caption (string), veil (boolean), stopButton (boolean). Keep hovered (pointer enter and leave, mouse and pen only — never touch) and focused (focus-visible) in state; "over" is either. Put the button and the caption in an absolutely positioned flex row, items-center justify-center gap-5, so the pair stays centred: the caption mounts at once when over, the card is not playing and a caption is set, and the button (motion layout) slides left by half the caption's width plus 10px on a spring with bounce 0.2, duration 0.4s; the button scales to 1.2 under the pointer. Veil: an inset-0 bg-black/25 layer whose opacity animates to 0 while playing, with the same spring. Stop button: while playing, the button is shown only when over, with a stop square instead of the triangle (a 10px rounded square). - play="pill" (default "circle"): instead of the circle, a motion.span pill in the middle (rounded-sm, bg-background text-foreground, px-4 py-2 text-sm font-medium, shadow-xs) holding the caption, or the label, whose opacity animates to 0 while playing and back to 1 on pause (spring bounce 0, duration 0.4s). No growth, no slide, no stop square; the label prop must say what the pill says.











