# Range brush

> Pick a stretch of days by holding it: a lit window over a year of hairlines that glides when thrown, stretches from either edge and settles on whole days.

Choosing "the last 30 days" in a date picker means choosing blind: you only see what the stretch held after you pick it. Range brush puts the choice on the data. The whole history is a silhouette ruled in hairlines, and the chosen stretch is lit inside a hairline window. Drag inside the window and it slides; let go and it glides on with your speed, settles on whole days, and pulls back like a rubber band at either end. Drag an edge to widen or narrow it, never under the shortest span you set, or press outside and drag to draw a new one. The days the window leaves do not go dark at once: they cool behind it, so you can see where it came from. When it settles, the stretch's total and its change against the same number of days before it roll to their figures. Two springs and one canvas: nothing re-renders while you drag.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/range-brush.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): `number-roll`
- Docs and live preview: https://hairlineui.com/ui/range-brush
- Registry item (source): https://hairlineui.com/r/range-brush.json

## Usage

```tsx
import { RangeBrush } from "@/components/range-brush";

<RangeBrush
  title="Signups"
  data={days} // [{ key: "2026-03-14", value: 812, label: "14 Mar", tick: "Mar" }, …]
  defaultValue={[335, 365]}
  onValueChange={([from, to]) => setRange(days[from].key, days[to - 1].key)}
/>
```

## Driving a dashboard

Keep the chosen stretch in the URL so the rest of the page and a shared link follow it.

```tsx
"use client";
import { useRouter, useSearchParams } from "next/navigation";
import { RangeBrush, type RangeBrushDatum } from "@/components/range-brush";

export function DashboardRange({ days }: { days: RangeBrushDatum[] }) {
  const router = useRouter();
  const params = useSearchParams();
  const from = days.findIndex((d) => d.key === params.get("from"));
  const to = days.findIndex((d) => d.key === params.get("to"));
  const value: [number, number] = from >= 0 && to >= from ? [from, to + 1] : [days.length - 30, days.length];
  return (
    <RangeBrush
      title="Signups"
      data={days}
      value={value}
      onValueChange={([a, b]) => router.replace(`?from=${days[a].key}&to=${days[b - 1].key}`, { scroll: false })}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `RangeBrushDatum[]` | – | One per day, oldest first: key, value, label (in the caption) and an optional tick. |
| `value / defaultValue` | `[number, number]` | `the last 30 days` | Start and end as day indexes, the end not included; controlled or not. |
| `onValueChange` | `(value) => void` | – | Called when a drag or key press settles on a new stretch. |
| `minSpan` | `number` | `7` | The shortest stretch, in days. |
| `title` | `string` | `"Signups"` | Above the total. |
| `format / locales` | `Intl.NumberFormatOptions / string` | – | How the total reads. |
| `color` | `string` | `var(--chart-1)` | Any CSS colour for the bars; read again when the theme changes. |

## States

- **arrive**: In view for the first time, the year rises from the baseline in a wave from the left (600ms each, spread over about half a second) with the window lit.
- **pan**: Dragging inside the window moves it 1:1; past either end it gives less and less. On release it glides on with the hand's speed and settles on whole days on two springs.
- **resize**: Dragging an edge (10px either side grabs it) moves that edge alone, never closer than the shortest span to the other.
- **draw**: Pressing outside the window and dragging draws a new one from where you pressed.
- **trail**: Days the window leaves keep their light and cool over about 0.6s.
- **settle**: When it settles, the total and its change against the same number of days before roll (900ms); the caption follows the window as it moves.
- **reduced motion**: No wave, glide or trail: the window lands where you let go, on whole days.

## What it handles

A date range picker asks for dates before it shows what they hold, so finding "the launch week" takes several tries.

- **Choose on the data**: The window sits on a year of daily figures, so a spike or a quiet week is easy to frame.
- **Feels like an object**: It glides when thrown, settles on whole days and rubber-bands at the ends, on springs that keep their speed.
- **Three ways to change it**: Drag inside to move it, drag an edge to resize it, or draw a new one outside it.
- **The figures you need**: The total of the stretch and its change against the same length before it roll when it settles.
- **Light where it has been**: Days the window leaves cool behind it instead of going dark at once.
- **Keyboard and screen readers**: The window moves with arrow keys (Shift for a week); each edge is a slider; the stretch is announced.

## Replaces

a date range picker, a chart brush, a zoom slider, a range total, a period comparison chip

## Where it fits

- **Analytics date ranges**: Pick the stretch a dashboard shows by seeing the year behind it.
- **Report builders**: Choose the period of an export or a report on its own data.
- **Incident and log review**: Narrow a long history down to the days around a spike.
- **Billing and usage history**: Select a run of days to total usage or spend.

## Notes

- The window is one tab stop: Left and Right move it a day, Shift a week. Each edge is a slider with the day as its value text. The chosen stretch and its total are announced politely.
- Every day's figure is in a visually hidden table.
- The history is drawn on one canvas through a rule of 2px hairlines; the window's edges are two springs from createSpring, and a drag writes to them directly, so nothing re-renders until it settles.
- Installs Number roll. With reduced motion the window lands without gliding and leaves no trail.

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