# Threshold line

> Set an alert by seeing what it would have done: drag a line across the last 30 days and every day over it turns red while the count of alerts rolls.

Alert settings usually ask for a number in a field, and you find out whether 400ms was right when the pager goes off at night. Threshold line puts the number on the chart. Drag the line, or its value tag, up and down the last 30 days. Every bar is a stack of 2px hairlines over a faint ruled column, and as the line passes under a bar its hairlines turn red from the line up, one by one, so the part of each day over the limit is exactly the part that is red. A dot drops into the strip under each day that would have fired, and the count in the header rolls. Let go mid-pull and the line keeps its speed, then settles on the nearest round step; past either end it pulls back like a rubber band. For an alert when something drops, days under the line turn red and the shortfall up to the line shows as a pale block. The line is one spring and the bars move by transform only, so dragging never lays out the page.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/threshold-line.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`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/threshold-line
- Registry item (source): https://hairlineui.com/r/threshold-line.json

## Usage

```tsx
import { ThresholdLine } from "@/components/threshold-line";

<ThresholdLine
  title="Alert when p95 latency is above the line"
  period="would have fired in the last 30 days"
  data={days} // [{ key: "2026-10-14", value: 512, label: "Tue, 14 Oct", tick: "14 Oct" }, …]
  defaultValue={450}
  step={10}
  format={{ style: "unit", unit: "millisecond", unitDisplay: "short" }}
  onValueCommit={(ms) => saveAlert({ p95Above: ms })}
/>
```

## Saving the alert

Load the last 30 days on the server, and save the threshold when a drag or key press is done.

```tsx
"use client";
import { ThresholdLine, type ThresholdLineDatum } from "@/components/threshold-line";

export function LatencyAlert({ days, saved }: { days: ThresholdLineDatum[]; saved: number }) {
  return (
    <ThresholdLine
      title="Alert when p95 latency is above the line"
      period="would have fired in the last 30 days"
      label="Latency alert threshold"
      data={days}
      defaultValue={saved}
      step={10}
      format={{ style: "unit", unit: "millisecond", unitDisplay: "short" }}
      onValueCommit={(ms) =>
        fetch("/api/alerts/latency", { method: "PUT", body: JSON.stringify({ above: ms }) })
      }
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `ThresholdLineDatum[]` | – | One per bar, oldest first: key, value, label and an optional tick. |
| `value / defaultValue` | `number` | `70% of the highest day` | Where the line is; controlled or not. |
| `onValueChange` | `(value: number) => void` | – | Called each time the line reaches a new step, while dragging too. |
| `onValueCommit` | `(value: number) => void` | – | Called once when a drag or key press is done: save here. |
| `direction` | `"above" \| "below"` | `"above"` | Fire when a day is over the line, or under it. |
| `min / max` | `number` | `0 / a round number over the data` | The ends of the scale and of the line. |
| `step` | `number` | `about a fortieth of the scale` | What the line settles on. |
| `title` | `string` | `"Alert when above the line"` | Over the count. |
| `period` | `string` | `"would have fired in this period"` | Under the count. |
| `label` | `string` | `"Threshold"` | The slider's accessible name. |
| `format / locales` | `Intl.NumberFormatOptions / string` | – | How the line's value and the scale read. |

## States

- **arrive**: In view for the first time, the bars grow from the baseline one after another (640ms, 18ms apart).
- **drag**: The line follows the pointer 1:1. Each bar it passes under fills red from the line up; a dot springs into the strip under each day that fires (320ms, slight overshoot) and the count rolls. The tag shows the step the line is on.
- **throw**: On release the line keeps its speed (capped so it never slams past) and settles on the nearest step on a spring; past the ends it rubber-bands back.
- **below**: With direction="below", days under the line turn red and a pale block shows the shortfall from each day up to the line.
- **keyboard**: Arrow keys move the line one step and Page Up and Down ten, on the same spring.
- **reduced motion**: No growth, throw or spring: the line moves straight to the value and dots appear without a pop.

## What it handles

A threshold typed into a field is a guess: nobody knows how often 400ms would have fired until it does, usually at night.

- **See it before you save it**: The days over the line turn red as you drag, and the number of alerts rolls in the header.
- **Exactly how far over**: Only the part of a bar above the line is red, so a near miss and a blow-out look different.
- **Above or below**: Alert when a metric is above the line, or when it drops below it with the shortfall shown.
- **A line that feels physical**: It follows the hand 1:1, keeps its speed when thrown, settles on round steps and rubber-bands at the ends.
- **Your format, your steps**: Milliseconds, percent or money through Intl.NumberFormat; snap to any step.
- **Keyboard and screen readers**: The tag is a slider: arrows move a step, Page keys ten; its value says how many alerts it means.

## Replaces

an alert threshold field, a slider beside a chart, an alert preview, a draggable annotation, a chart library

## Where it fits

- **Monitoring alerts**: Set when latency, error rate or CPU should page someone, against the last month.
- **Budget and spend limits**: Pick a daily spend cap and see which days would have gone over it.
- **Usage notifications**: Choose when a customer is told they are near their quota.
- **Business metric alerts**: Get told when signups or conversion drop below a line you can see.

## Notes

- The value tag is a vertical slider: arrow keys move a step, Page Up and Page Down ten, Home and End the ends. Its value text includes how many alerts it would raise.
- Every day's figure, and whether it would fire, is in a visually hidden table.
- Red is only used for days that would fire, always with a dot under them too.
- The line is one spring from createSpring; bars, fills and the line move by transform, so a drag never lays out the page.
- Installs Number roll and Text morph. With reduced motion the line moves straight to its value.

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