# Hold to start

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

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.

## Install

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

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

- npm: none
- Hairline UI components it needs (the CLI installs them too): `text-morph`
- Docs and live preview: https://hairlineui.com/ui/hold-to-start
- Registry item (source): https://hairlineui.com/r/hold-to-start.json

## Usage

```tsx
import { HoldToStart } from "@/components/hold-to-start";

<HoldToStart active={on} onActiveChange={setOn} label="Start session" activeLabel="End session">
  <SessionDetails on={on} />
</HoldToStart>
```

## Arming an alarm

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

```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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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` | `string` | `"Start"` | The button while off. |
| `activeLabel` | `string` | `"End"` | The button while on. |
| `holdingLabel` | `string` | `"Keep holding"` | The button while held. |
| `hint` | `string` | `"Hold to start"` | Shown after a tap that wasn’t held. |
| `holdMs` | `number` | `900` | How long to hold. |
| `holdToEnd` | `boolean` | `false` | Ending also needs a hold. |
| `palette` | `"azure" \| "solar" \| "prism" \| "dusk" \| LightPalette` | `"prism"` | The light’s colours. |

## 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.

## What it handles

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

- **A deliberate start**: The action needs a hold; a tap only shows the hint.
- **Light you can feel**: The card gathers light toward your finger as you hold.
- **Change under the light**: Your state changes as the crest crosses the card.
- **Ending**: A tap ends it, or a hold with holdToEnd.
- **Keyboard**: Hold Enter or Space; assistive tech that can’t hold acts directly.
- **Stays lit**: The rim keeps its light while it’s on.

## Replaces

hold to confirm button, confirm dialog, long press button, start session button, arm alarm toggle

## Where it fits

- **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.

## Notes

- 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.

License: MIT (https://hairlineui.com/license#components)
