# Streak chain

> “Don’t break the chain”, drawn big enough to care: today’s ring hangs open until you complete it, then it closes, fills with colour and the chain grows a ring.

Streaks are usually a number beside a flame, which says how long but not what’s at stake or how long you have. Streak chain draws the chain and the stakes. Every recent day is a ring joined to the next: done days in your colours, a frozen day pale with a frost mark that still holds, a missed day broken off and fallen where the chain once snapped. Today’s ring hangs open off the end and sways a little, with the time left to save it underneath, in amber once it gets late. Complete today and the ring swings up and closes, your colour pours round it from the joint while sparks flick off, then the whole chain moves along one ring and tomorrow’s empty ring slides in at the end: you watch the chain grow. Under it, the next milestone and how many days to go fill in the house’s hairline mark, and reaching a milestone sends a glint down the chain. Freezes left and your best streak sit beside the count. The days are yours: pass the history, whether today is done and when it ends; onCompleteToday saves it, and if your save fails the ring swings open again.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/streak-chain.json
```

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

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): `number-roll`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/streak-chain
- Registry item (source): https://hairlineui.com/r/streak-chain.json

## Usage

```tsx
import { StreakChain } from "@/components/streak-chain";

<StreakChain
  history={["done", "done", "frozen", "done", "done"]}
  today={doneToday}
  deadline={endOfToday}
  freezes={2}
  date="2026-11-12"
  onCompleteToday={() => fetch("/api/streak/today", { method: "POST" })}
/>
```

## From your check-ins

Build the history from the last few weeks of check-ins on the server, then let the chain save today.

```tsx
import { StreakChain, type StreakDay } from "@/components/streak-chain";
import { getCheckins, markToday } from "@/lib/streak";

export async function StreakCard({ userId }: { userId: string }) {
  const { days, doneToday, best, today } = await getCheckins(userId, 30); // days: { date, status: "done" | "missed" | "frozen" }[]
  return (
    <StreakChain
      history={days.map((d) => d.status as StreakDay)}
      defaultToday={doneToday}
      best={best}
      date={today}
      onCompleteToday={async () => {
        "use server";
        await markToday(userId);
      }}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `history` | `("done" \| "missed" \| "frozen")[]` | – | The days before today, oldest first. As many as fit are drawn. |
| `today / defaultToday` | `boolean` | – | Whether today is done, controlled or not. |
| `onCompleteToday` | `() => Promise<unknown> \| void` | – | Save today. Throw or reject to swing the ring open again. |
| `deadline` | `Date \| string \| number` | – | When today ends, for the time left under the chain. |
| `freezes` | `number` | – | Streak freezes still available, shown beside the count. |
| `best` | `number` | – | The longest streak so far. |
| `milestones` | `number[]` | `[7, 14, 30, 60, 100, 365]` | Counts to work toward; the next one shows under the chain. |
| `date` | `string` | – | Today, YYYY-MM-DD, for the day letters under the rings. |
| `title / actionLabel` | `string` | `"Daily streak" / "Complete today"` | The label and the button’s words. |
| `colors` | `[string, string]` | `["var(--chart-5)", "var(--chart-2)"]` | The chain runs from the first colour to the second. |

## States

- **open**: Today’s ring hangs at 26° from where it hooks into yesterday’s, a third of it open, in grey, swaying ±3° slowly while it’s on screen; under the chain, “5h 12m left today”, amber in the last three hours.
- **forge**: Completing today kicks the ring up past closed and lets it settle on a lively spring while its gap shuts; your two colours pour round it from the joint (560ms) and five sparks flick off it (520ms, staggered); the count rolls up.
- **grow**: 760ms later the whole chain slides one ring to the left (680ms) and tomorrow’s ring, dashed and empty, slides in at the end; the milestone line fills to its new share.
- **milestone**: When the new count reaches a milestone (7, 14, 30, 60, 100, 365 by default), the rings brighten one after another down the chain.
- **frozen and missed**: A frozen day is a pale ring with a frost mark that keeps the streak alive without adding to it; a missed day hangs broken and fallen, with no joints either side, and the count starts again after it.
- **refused**: If onCompleteToday throws or rejects, the ring swings open again and the count rolls back.
- **reduced motion**: No sway, sparks or sliding: the ring closes and the chain grows in place.

## What it handles

A number beside a flame says how long a streak is, but not that today is still open, how long is left to save it, what a freeze saved or where it last broke.

- **What’s at stake, at a glance**: Today’s ring hangs open at the end, with the hours left to save it, amber when late.
- **A moment worth coming back for**: The ring closes, colour pours round it, and the chain grows a ring.
- **Freezes and misses**: A frozen day holds the chain; a missed day hangs broken where it snapped.
- **The next goal**: Days to the next milestone, filling as you go; a glint when you reach it.
- **Your data stays the truth**: History in, today out; a failed save swings the ring open again.
- **Readable without the picture**: A hidden list of the days, a named button and an announced streak.

## Replaces

a streak counter, a habit tracker, a daily check-in, a calendar of done days, a milestone progress bar

## Where it fits

- **Learning apps**: Lessons done each day, the way language and coding apps keep people coming back.
- **Habit trackers**: Workouts, meditation, reading or no-sugar days.
- **Writing and journaling**: A daily word count or entry kept up.
- **Dev and community**: Daily commits, check-ins or challenge days.

## Notes

- The chain is drawn for sighted people; a hidden list names every day, the button is named by what it does, and completing today is announced with the new streak. The time left updates every 30 seconds and is never announced.
- Rings are SVG; today’s ring turns and closes on two springs from ui-interaction-motion.ts (installed with it); the pour, sparks and growth are one-off Web Animations; the sway runs only while the card is on screen.
- Fits its width: about one ring per 46px, between five and nine days.
- Installs Number roll and Text morph. With reduced motion everything changes in place.

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