Skip to content
Browse documentation

A card whose main action is held: light gathers toward your finger while you hold, and bursts across the card when it starts.

Used forSessionsSecurityGoing liveScenes

Install with the shadcn CLI

$ npx shadcn@latest add https://hairlineui.com/r/hold-to-start.json

Registered the namespace? Then it’s shadcn add @hairline/hold-to-start. Set it up

Templates

Need the whole page?

61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.

All 61 templates

Where it’s used

  • Sessions

    Start a focus block, a workout or a recording you mean to start.

  • Security

    Arm an alarm or lock down a space, and disarm it with a hold too.

  • Going live

    Start a stream, a broadcast or a sale at its moment.

  • Scenes

    Run Goodnight for the whole home with one deliberate hold.

What it handles for you

A tap starts things by accident, and a confirm dialog interrupts a moment that should feel deliberate.

Instead of wiring uphold to confirm buttonconfirm dialoglong press buttonstart session buttonarm alarm toggle
  1. A deliberate start

    The action needs a hold; a tap only shows the hint.

  2. Light you can feel

    The card gathers light toward your finger as you hold.

  3. Change under the light

    Your state changes as the crest crosses the card.

  4. Ending

    A tap ends it, or a hold with holdToEnd.

  5. Keyboard

    Hold Enter or Space; assistive tech that can’t hold acts directly.

  6. Stays lit

    The rim keeps its light while it’s on.

Overview

Starting a focus session, arming an alarm, going live: some actions should take a moment of intent, and a confirm dialog is the wrong shape for it. Hold to start puts the hold on the card itself. Press the button and, after a short grace, light gathers into the card toward your finger: a halo closes in from the edges, starlight dust is pulled toward the press, the content draws back a fraction and the button fills from the left. Let go early and it all relaxes back; a quick tap just says “Hold to start” and pulses once. Hold to the end and the gathered light bursts as a thin crest from your finger across the card, your change lands under it, and the rim stays lit while it’s on. Ending is a tap by default, or a hold if you ask for one.

States

hold
After 140ms the charge builds to 100% over the rest of holdMs (900ms by default): the halo closes to 28% of its reach, dust is pulled up to 34% of the way to the finger, the content scales to 98.8% with a 1.1px blur, and the button fills.
release
Let go early and the charge relaxes back over about 220ms and the fill drains over 260ms.
tap
A press under 200ms morphs the label to the hint for 1.4s with a small pulse of light.
start
At 100% a crest ring spreads from the finger over 1.4s; at 36% the content is most out of focus (7.8px) and onActiveChange runs there. The rim blooms and settles.
end
While active, a tap (or a hold with holdToEnd) plays the same crest and calls onActiveChange(false).
reduced motion
No light; a hold still has to be held, and the change lands at once.

Usage

usage.tsx
import { HoldToStart } from "@/components/hold-to-start";<HoldToStart active={on} onActiveChange={setOn} label="Start session" activeLabel="End session">  <SessionDetails on={on} /></HoldToStart>

Works with

Arming an alarm

Send the request the moment the hold completes, and let the state change land under the light.

example.tsx
"use client";import { useState } from "react";import { HoldToStart } from "@/components/hold-to-start";export function AlarmCard() {  const [armed, setArmed] = useState(false);  return (    <HoldToStart      active={armed}      holdToEnd      label="Arm alarm"      activeLabel="Disarm"      onHoldComplete={() => fetch("/api/alarm", { method: "POST", body: JSON.stringify({ armed: !armed }) })}      onActiveChange={setArmed}    >      <h3>{armed ? "Armed" : "Home alarm"}</h3>    </HoldToStart>  );}

Props

active
boolean
Whether it’s on.
onActiveChange
(active: boolean) => void
Called with the new state when the light covers the card.
onHoldComplete
() => void
Called the moment a hold completes, before the change lands: send your request here.
children
ReactNode
The card’s content above the button.
label= "Start"
string
The button while off.
activeLabel= "End"
string
The button while on.
holdingLabel= "Keep holding"
string
The button while held.
hint= "Hold to start"
string
Shown after a tap that wasn’t held.
holdMs= 900
number
How long to hold.
holdToEnd= false
boolean
Ending also needs a hold.
palette= "prism"
"azure" | "solar" | "prism" | "dusk" | LightPalette
The light’s colours.

Accessibility and motion

  • The hold runs on one requestAnimationFrame loop; the charge and the fill are written straight to the canvas and the button, with no re-render per frame.
  • The light is a 2D canvas over the card, drawn only while charging or while a crest crosses.
  • The button keeps the pointer captured, so a finger that drifts off it doesn’t cancel the hold; leaving the page or a cancelled pointer does.
  • The button says “Press and hold to start” to screen readers. A click with no pointer or key behind it (from assistive tech, which can’t hold) acts at once.
  • Reduced motion drops the light; the hold itself stays.

Requirements

React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

The CLI also installs Text morph.

Source

"use client";import * as React from "react";import { LightSurface, clamp, useLightReducedMotion, type LightPalette, type LightPaletteName, type LightPoint, type LightSurfaceHandle } from "./light-surface";import { TextMorph } from "./text-morph";import { INTERACTION_FOCUS } from "./ui-interaction-motion";/* ───────────────────────────────────────────────────────── * HOLD TO START: a card whose main action is held, not tapped * *   hold     light gathers into the card toward your finger: *            a halo closes in, dust is pulled toward the press, *            the content draws back a fraction and the button *            fills from the left *   release  let go early and it all relaxes back; a quick tap *            just says "Hold to start" and pulses once *   start    held to the end, the gathered light bursts as a *            crest from your finger across the card; your *            change lands under it and the rim stays lit while *            it's on *   end      while it's on, a tap ends it with the same crest *            (or a hold, if you ask for one) * * Keyboard: hold Enter or Space. Reduced motion: no light; a * hold still has to be held, and the change lands at once. * ───────────────────────────────────────────────────────── */export interface HoldToStartProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "onChange"> {  /** Whether it's on. */  active: boolean;  /** Called with the new state at the moment the light covers the card: change your state here. */  onActiveChange: (active: boolean) => void;  /** Called the moment a hold completes, before the change lands: send your request here. */  onHoldComplete?: () => void;  /** The card's content above the button. */  children: React.ReactNode;  label?: string;  activeLabel?: string;  /** Shown while held. */  holdingLabel?: string;  /** Shown for a moment after a tap that wasn't held. */  hint?: string;  /** How long to hold, ms. */  holdMs?: number;  /** Ending also needs a hold. */  holdToEnd?: boolean;  palette?: LightPaletteName | LightPalette;}const GRACE = 140;export function HoldToStart({  active,  onActiveChange,  onHoldComplete,  children,  label = "Start",  activeLabel = "End",  holdingLabel = "Keep holding",  hint = "Hold to start",  holdMs = 900,  holdToEnd = false,  palette = "prism",  className = "",  ...props}: HoldToStartProps) {  const surface = React.useRef<LightSurfaceHandle>(null);  const button = React.useRef<HTMLButtonElement>(null);  const fill = React.useRef<HTMLSpanElement>(null);  const hold = React.useRef<{ start: number; origin: LightPoint; raf: number; fired: boolean } | null>(null);  const hintTimer = React.useRef(0);  const reduced = useLightReducedMotion();  const [phase, setPhase] = React.useState<"rest" | "holding" | "hint">("rest");  const needsHold = !active || holdToEnd;  const live = React.useRef({ active, onActiveChange, onHoldComplete });  React.useLayoutEffect(() => {    live.current = { active, onActiveChange, onHoldComplete };  });  React.useEffect(    () => () => {      if (hold.current) cancelAnimationFrame(hold.current.raf);      window.clearTimeout(hintTimer.current);    },    [],  );  const setFill = (p: number, animate: boolean) => {    const el = fill.current;    if (!el) return;    el.style.transition = animate && !reduced ? "transform 260ms cubic-bezier(0.16,1,0.3,1), opacity 260ms ease-out" : "none";    el.style.transform = `scaleX(${p})`;    el.style.opacity = p > 0 ? "1" : "0";  };  /** Where the press is, 0 to 1 inside the card. */  const originOf = (clientX?: number, clientY?: number): LightPoint => {    const card = surface.current?.element();    const btn = button.current;    if (!card) return { x: 0.5, y: 0.88 };    const c = card.getBoundingClientRect();    let x = clientX;    let y = clientY;    if (x === undefined || y === undefined || (x === 0 && y === 0)) {      const b = btn?.getBoundingClientRect();      x = b ? b.left + b.width / 2 : c.left + c.width / 2;      y = b ? b.top + b.height / 2 : c.bottom;    }    return { x: clamp((x - c.left) / c.width, 0.06, 0.94), y: clamp((y - c.top) / c.height, 0.06, 0.96) };  };  const fire = (origin: LightPoint) => {    const next = !live.current.active;    surface.current?.charge(0);    setFill(0, true);    setPhase("rest");    const s = surface.current;    if (!s) return live.current.onActiveChange(next);    s.wave({ direction: "radial", origin, onMidpoint: () => live.current.onActiveChange(next) });  };  const begin = (origin: LightPoint) => {    if (hold.current) return;    window.clearTimeout(hintTimer.current);    const h = { start: performance.now(), origin, raf: 0, fired: false };    hold.current = h;    const step = (now: number) => {      if (hold.current !== h) return;      const elapsed = now - h.start;      if (elapsed > GRACE) {        const p = clamp((elapsed - GRACE) / (holdMs - GRACE), 0, 1);        setPhase("holding");        surface.current?.charge(p, h.origin);        setFill(p, false);        if (p >= 1) {          h.fired = true;          hold.current = null;          live.current.onHoldComplete?.();          fire(h.origin);          return;        }      }      h.raf = requestAnimationFrame(step);    };    h.raf = requestAnimationFrame(step);  };  /** Let go: before the end it relaxes; a short tap either acts (no hold needed) or hints. */  const end = (commitTap: boolean) => {    const h = hold.current;    if (!h) return;    hold.current = null;    cancelAnimationFrame(h.raf);    if (h.fired) return;    surface.current?.charge(0);    setFill(0, true);    const tap = performance.now() - h.start <= GRACE + 60;    if (!commitTap) return setPhase("rest");    if (!needsHold) return fire(h.origin);    if (tap) {      setPhase("hint");      // A small pulse of light says something is here to hold.      surface.current?.charge(0.22, h.origin);      window.setTimeout(() => surface.current?.charge(0), 120);      hintTimer.current = window.setTimeout(() => setPhase("rest"), 1400);      return;    }    setPhase("rest");  };  const text = phase === "holding" ? holdingLabel : phase === "hint" ? hint : active ? activeLabel : label;  return (    <LightSurface ref={surface} palette={palette} direction="radial" lit={active} className={`flex flex-col rounded-[30px] ${className}`} {...props}>      <div className="flex h-full flex-col px-6 pb-6 pt-7">        <div className="flex-1">{children}</div>        <button          ref={button}          type="button"          aria-pressed={active}          onPointerDown={(e) => {            if (e.button !== 0) return;            e.currentTarget.setPointerCapture(e.pointerId);            begin(originOf(e.clientX, e.clientY));          }}          onPointerUp={() => end(true)}          onPointerCancel={() => end(false)}          onLostPointerCapture={() => end(false)}          onKeyDown={(e) => {            if ((e.key === "Enter" || e.key === " ") && !e.repeat) {              e.preventDefault();              begin(originOf());            }          }}          onKeyUp={(e) => {            if (e.key === "Enter" || e.key === " ") {              e.preventDefault();              end(true);            }          }}          onBlur={() => end(false)}          onContextMenu={(e) => e.preventDefault()}          // A click with no pointer or key behind it comes from assistive tech, which can't hold: act on it.          onClick={(e) => {            if (e.detail === 0 && !hold.current) fire(originOf());          }}          className={`relative mt-6 flex h-[50px] w-full cursor-pointer touch-none select-none items-center justify-center overflow-clip rounded-full bg-primary px-6 text-[15px] font-medium tracking-[-0.01em] text-primary-foreground [-webkit-touch-callout:none] transition-[scale] duration-200 ease-[cubic-bezier(0.16,1,0.3,1)] active:scale-[0.98] motion-reduce:active:scale-100 ${INTERACTION_FOCUS}`}        >          <span            ref={fill}            aria-hidden            className="pointer-events-none absolute inset-0 origin-left opacity-0"            style={{ transform: "scaleX(0)", background: "linear-gradient(90deg, rgb(255 255 255 / 0.14), rgb(255 255 255 / 0.3))" }}          />          <TextMorph className="relative">{text}</TextMorph>          {needsHold && <span className="sr-only">. Press and hold to {active ? "end" : "start"}.</span>}        </button>      </div>    </LightSurface>  );}

Registry item: /r/hold-to-start.json