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
Install
pnpm dlx shadcn@4.21.1 add @frictionborn/ambient-hero
Playground
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
| Prop | Type | Default | What it does |
|---|---|---|---|
headline | string | none | Required. Primary document h1 heading rendered by TextReveal by word. |
body | string | none | Required. Supporting description copy below the headline. |
primaryCta | AmbientHeroCta = { label: string; href?: string; onClick?: () => void } | none | Required. 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. |
background | React.ReactNode | none | Optional. Custom background slot overriding the ambient generator variant. |
eyebrow | string | none | Optional. Small pill tag displayed above the headline. |
secondaryCta | AmbientHeroCta = { label: string; href?: string; onClick?: () => void } | none | Optional. Secondary action link with magnetic pull. Rendered as an <a>; href falls back to '#'. |
showPauseButton | boolean | true | Renders a pause/resume button that stops and restarts the hero background only. |
paused | boolean | false | Universal pause prop. Freezes the ambient background variant only (not a custom background slot, the headline or the buttons). |
nonce | string | none | Optional CSP nonce forwarded to the <style> element of the headline reveal. |
className | string | none | Optional. 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. |
style | React.CSSProperties | none | Optional. No default. Inline styles on the root header element, merged last (consumer wins). |
ref | React.Ref<HTMLElement> | none | Receives the root <header> element. |
palette | "fire" | "ice" | "neon" | "mono" | "custom" | none | Colours 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.
| Measure | Result |
|---|---|
| Size, gzip | 3.64 KB at load, 0.02 KB loaded later |
| Layout shift | 0 |
| Frames when nothing should move | off screen 0, hidden tab 0, reduced motion 0 |
| axe accessibility scan | 0 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.
| Environment | Tier | Result | Date | Notes |
|---|---|---|---|---|
| Chromium Desktop (SwiftShader) | 3 | pass | 2026-10-21 | 20 passed, 0 failed |
| Chromium Mobile (Pixel 7 emulation) | 2 | pass | 2026-10-21 | 18 passed, 0 failed |
| Firefox Desktop | 3 | pass | 2026-10-21 | 19 passed, 0 failed |
| WebKit Desktop | 3 | pass | 2026-10-21 | 18 passed, 0 failed |
| WebKit Mobile (iPhone 14 emulation) | 2 | pass | 2026-10-21 | 16 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
| Tier | What it does |
|---|---|
| T3 Full | WebGL background at DPR <= 2; fine-pointer magnetic pull; headline animates by word only if the component mounts on the client |
| T2 Standard | WebGL 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 Lite | Poster 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 Static | CSS 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
styleattributes, so allowstyle-src-attr 'unsafe-inline'.