# Lens bars

> A whole year of days in one card, and a lens to read them: the bars under the pointer spread apart and widen, so any one day out of 365 is easy to land on.

A year of daily figures in a card leaves each bar thinner than a pixel, so most dashboards fall back to weeks or months and the launch day disappears into an average. Lens bars keeps every day and gives the pointer a lens. Every bar is drawn as a stack of 2px hairlines over a faint ruled field, so where the year is dense the lines run together into one engraved silhouette, with no comb of thin bars to shimmer. The bars under it spread apart and widen, the day you are on to about 18px, while the rest of the year squeezes aside to make room. The day under the pointer stays exactly where it is, so the lens never slides away from what you meant. The bars nearest it light up, falling off evenly from the centre, and a readout above shows that day and its figure. Bars you sweep past keep their light for a moment and fade back one after another, a short trail of where you have been. Leave and the year lies flat again in about 0.3s. New figures ease each bar to its new height in a wave that runs out from the day you last read. Under the chart sit the daily average, the best day (point at it and the lens opens there) and the last 30 days against the 30 before. It is drawn on one canvas, so 365 bars cost no more than 30.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/lens-bars.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/lens-bars
- Registry item (source): https://hairlineui.com/r/lens-bars.json

## Usage

```tsx
import { LensBars } from "@/components/lens-bars";

<LensBars
  title="Signups"
  caption="Last 365 days"
  data={days} // [{ key: "2026-03-14", value: 812, label: "Sat, 14 Mar", tick: "Mar" }, …]
/>
```

## From your database

Count by day on the server, fill the days with nothing in them, and put a tick on the first of each month.

```tsx
import { LensBars, type LensBarsDatum } from "@/components/lens-bars";
import { db } from "@/lib/db";

export async function SignupsCard() {
  const rows = await db.signupsByDay({ days: 365 }); // [{ day: "2026-03-14", count: 812 }, …]
  const counts = new Map(rows.map((r) => [r.day, r.count]));
  const data: LensBarsDatum[] = Array.from({ length: 365 }, (_, i) => {
    const date = new Date(Date.now() - (364 - i) * 86_400_000);
    const key = date.toISOString().slice(0, 10);
    return {
      key,
      value: counts.get(key) ?? 0,
      label: date.toLocaleDateString("en-GB", { weekday: "short", day: "numeric", month: "short" }),
      tick: date.getDate() === 1 ? date.toLocaleDateString("en-GB", { month: "short" }) : undefined,
    };
  });
  return <LensBars title="Signups" caption="Last 365 days" data={data} />;
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `LensBarsDatum[]` | – | One per bar, oldest first: key, value, label (in the readout) and an optional tick (under the bar). |
| `title` | `string` | `"Signups"` | Above the total. |
| `caption` | `string` | – | Under the total, e.g. "Last 365 days". |
| `total` | `number` | `the sum of data` | The figure in the header. |
| `format` | `Intl.NumberFormatOptions` | – | How the total and the readout read. |
| `locales` | `string \| string[]` | – | For number formatting. |
| `color` | `string` | `var(--chart-1)` | Any CSS colour for the bars; read again when the theme changes. |
| `onActiveChange` | `(datum, index) => void` | – | Called when the day under the lens changes, with null when it closes. |

## States

- **arrive**: In view for the first time, the bars grow from the baseline in a wave from the left (640ms each, spread over about 0.5s) and the total rolls up from zero.
- **point**: The lens opens on a spring (about 0.3s, no overshoot). Days within six either side of the pointer widen, the one under it to about 18px; the rest of the year squeezes aside. The day under the pointer stays fixed. Nearby bars light up, falling off smoothly from the centre, and the rest dim; the readout shows the day and its figure with a hairline stem down to its bar.
- **sweep**: The lens follows the pointer on a stiff spring. Bars it leaves keep their light and fade back over about 0.4s, so a sweep leaves a short trail. Month ticks ride along with their bars and fade where the squeeze crowds them.
- **leave**: The lens closes on the same spring and the year lies flat again; the readout fades with it.
- **data**: New figures ease each bar to its new height (520ms) in a wave running out from the day you last read (up to 280ms apart). A change mid-ease starts from where the bars are.
- **reduced motion**: No growth, waves or trail: the lens still widens the days (it is how you pick one) but opens and moves at once.

## What it handles

With 365 bars in a card, each bar is thinner than a pixel and nobody can point at one. Most charts give up and show weeks, losing the days that mattered.

- **Every day readable**: The pointer widens the days around it to about 18px, however many days are in the card.
- **The lens stays put**: The day under the pointer never moves while the lens opens, so you land on the day you aimed at.
- **A trail of where you have been**: Bars you pass stay lit for a moment and fade back, so a sweep shows the stretch you read.
- **Phones too**: Press and slide to move the lens; lift and it stays on that day until you tap somewhere else.
- **Cheap at any size**: One canvas and one pure layout function: 365 or 3,650 bars cost the same, and nothing runs at rest.
- **Keyboard and screen readers**: Arrow keys move a day, Shift a week, Page keys a month; the day is announced, and every figure is in a hidden table.

## Replaces

a chart library, a date range zoom, a weekly roll-up, a hover tooltip, a brush to zoom in

## Where it fits

- **Analytics overviews**: Daily signups, visits or orders for the last year, with every day still readable.
- **Revenue dashboards**: Daily revenue across a year, so a launch or an outage shows as the day it happened.
- **Usage and billing pages**: API calls, minutes or credits used per day, for the whole billing year.
- **Status and uptime history**: A year of daily incidents or response times in one strip.

## Notes

- The plot is one tab stop: Left and Right move a day, Shift a week, Page Up and Page Down thirty days, Home and End the ends; the day is announced politely and Escape closes the lens.
- Every figure is in a visually hidden table, with the total in its caption.
- Bars are drawn on one canvas at the screen's pixel density, through a rule of 2px hairlines counted from the baseline and placed on device pixels; the readout, stem and ticks are elements moved by transform. Nothing runs while the chart is at rest.
- The lens is two springs from createSpring (where it is, how open) and a pure layout function, so it can be re-aimed at any moment without a jump.
- Installs Number roll. With reduced motion the lens still widens the days but moves at once, with no trail or waves.

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