Skip to content

Composition

AmbientHero

A complete hero: a living background, a headline that arrives word by word, and buttons that lean towards the pointer.

Hero composition: ambient canvas (mesh/noise/particles) + TextReveal + MagneticButton

  • Composition
  • Reduced motion: static
  • 3.64 KB gzip
  • 1 WebGL context
  • Layout shift 0
View the source Spec sheet as Markdown

Install

Install
pnpm dlx shadcn@4.21.1 add @frictionborn/ambient-hero

Playground

Palette
Your code
import { AmbientHero } from "@/components/ui/ambient-hero";

<AmbientHero
  headline="Calm motion, struck from a single spark."
  body="One or two plain sentences."
  primaryCta={{ label: "Get started", href: "/start" }}
 />

In a full example

The full example loads as you scroll to it.

Accessibility

  • Single h1 heading (rendered by TextReveal). A scrim built from the host --background token sits between the canvas and the text, so it follows the light or dark theme; it is a contrast aid, not a guarantee, and contrast over the live canvas is not computed at runtime: verify it for your content in both themes. Measured on real pixels over the live canvas in a fresh Next 16 app with shadcn's default tokens (3 variants x light/dark x 1440/390 px, sample copy): every text element at least 10:1. The scrim is strong, so a bolder background needs mesh-gradient (or another background item) directly instead of this composition. Every colour is a host token (--background, --foreground, --primary, --primary-foreground, --muted-foreground, --secondary, --border) with a system-colour fallback. The pause button stops only the hero background; it does not touch the page's other motion or SmoothScroll's scrolling. All text stays in the accessibility tree.
  • Keyboard: Tab reaches the pause button (when shown), then the CTA links, with default browser focus rings; Enter activates links, Enter or Space activates the pause button
  • Touch: Touch devices (coarse pointer) get no magnetic pull; CTA links and the pause button respond to direct tap
  • WCAG criteria it is built for: 2.1.1, 2.2.2, 2.3.1

Props

PropTypeDefaultWhat it does
headlinestringnoneRequired. Primary document h1 heading rendered by TextReveal by word.
bodystringnoneRequired. Supporting description copy below the headline.
primaryCtaAmbientHeroCta = { label: string; href?: string; onClick?: () => void }noneRequired. Primary action link with magnetic pull. Rendered as an <a>; href falls back to '#'.
variant"mesh" | "noise" | "particles""mesh"Selects which ambient background to mount (exactly one WebGL context). Its settings are fixed: mesh speed 0.3, noise speed 0.4 scale 1.8, particles count 2500 speed 0.4.
backgroundReact.ReactNodenoneOptional. Custom background slot overriding the ambient generator variant.
eyebrowstringnoneOptional. Small pill tag displayed above the headline.
secondaryCtaAmbientHeroCta = { label: string; href?: string; onClick?: () => void }noneOptional. Secondary action link with magnetic pull. Rendered as an <a>; href falls back to '#'.
showPauseButtonbooleantrueRenders a pause/resume button that stops and restarts the hero background only.
pausedbooleanfalseUniversal pause prop. Freezes the ambient background variant only (not a custom background slot, the headline or the buttons).
noncestringnoneOptional CSP nonce forwarded to the <style> element of the headline reveal.
classNamestringnoneOptional. No default. Additional CSS class names on the root header element. Any other HTML attribute (id, data-*, aria-*, event handlers) is spread on the root element; handlers the item uses itself are composed, not replaced.
styleReact.CSSPropertiesnoneOptional. No default. Inline styles on the root header element, merged last (consumer wins).
refReact.Ref<HTMLElement>noneReceives the root <header> element.
palette"fire" | "ice" | "neon" | "mono" | "custom"noneColours of the background variant from a palette (DESIGN.md A8): fire, ice, neon, mono, or custom. Leave it out to keep the host's tokens.

Measured on the bench

Measured by the automated bench at commit 801163e on 2026-10-21. These numbers are written by the bench, never by hand.

MeasureResult
Size, gzip3.64 KB at load, 0.02 KB loaded later
Layout shift0
Frames when nothing should moveoff screen 0, hidden tab 0, reduced motion 0
axe accessibility scan0 serious, 0 critical

Browsers it ran in

Automated Playwright runs, some with device emulation. Results from physical phones and tablets are still pending, so none are listed.

EnvironmentTierResultDateNotes
Chromium Desktop (SwiftShader)3pass2026-10-2120 passed, 0 failed
Chromium Mobile (Pixel 7 emulation)2pass2026-10-2118 passed, 0 failed
Firefox Desktop3pass2026-10-2119 passed, 0 failed
WebKit Desktop3pass2026-10-2118 passed, 0 failed
WebKit Mobile (iPhone 14 emulation)2pass2026-10-2116 passed, 0 failed, 1 flaky (passed on retry)

On different devices

Reduced motion (static): Renders the static CSS gradient poster background with 0 WebGL canvases and 0 animation frames; headline renders as plain text without splitting or keyframes; buttons remain static

TierWhat it does
T3 FullWebGL background at DPR <= 2; fine-pointer magnetic pull; headline animates by word only if the component mounts on the client
T2 StandardWebGL background at DPR <= 1.5; magnetic pull only with a fine pointer; headline animates by word (60 ms stagger) only if the component mounts on the client
T1 LitePoster background; no magnetic pull; the headline animates by word with a 40 ms stagger only if the component mounts on the client (coarse pointer with low-end hints)
T0 StaticCSS gradient poster background (no WebGL), headline as plain static text, CTAs without magnetic pull (server render, prefers-reduced-motion, Save-Data, no WebGL2)

Content Security Policy

  • Works without 'unsafe-eval'.
  • Needs no reveal gate.
  • Sets inline style attributes, so allow style-src-attr 'unsafe-inline'.

Goes well with