# Pillar chart

> A period of activity as glass pillars on dark lacquer: point at one and it turns white, switch the range and the new pillars rise in a wave.

Weekly focus time, distance run, hours played: a stat card with a few bars is everywhere, and most of them are flat rounded rectangles that snap when you change the range. Pillar chart is an object with its own finish, a dark lacquered card in your colour with frosted glass capsules for pillars and a fine curve running over their tops. Point at a pillar and it turns solid white while a small lime marker glides above it and the line under the total says what it is. Switch between week, month and year and the pill slides to the choice, the pillars on show sink away, the new ones rise from the floor in a wave from the side you moved toward, the curve draws itself again, and the total and its change roll to their new figures. It looks the same on a light page or a dark one.

## Install

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

## Usage

```tsx
import { PillarChart } from "@/components/pillar-chart";

<PillarChart
  title="Focus time"
  unit=" hrs"
  ranges={[{ id: "week", label: "W", total: 48.2, change: 12.4, bars: [{ label: "Mon", value: 5.4 }, { label: "Tue", value: 6.8 }] }]}
/>
```

## Focus time from your API

One request per range, or all three at once; the chart only needs the totals and the bars.

```tsx
"use client";
import { useEffect, useState } from "react";
import { PillarChart, type PillarRange } from "@/components/pillar-chart";

export function FocusCard() {
  const [ranges, setRanges] = useState<PillarRange[] | null>(null);
  useEffect(() => {
    fetch("/api/focus/ranges").then((r) => r.json()).then(setRanges);
  }, []);
  if (!ranges) return null;
  return <PillarChart title="Focus time" unit=" hrs" ranges={ranges} tone="cobalt" />;
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ranges` | `{ id, label, name?, total, change?, bars: { label, value, detail? }[], focus? }[]` | – | Each range: the switch label (W), its name for screen readers (Week), the total, the change in percent and the bars. |
| `value / defaultValue` | `string` | `the first range` | The range on show, by id; controlled or not. |
| `onValueChange` | `(id: string) => void` | – | Called when the range changes. |
| `title / icon` | `string / ReactNode` | `"Activity"` | Top left. |
| `unit` | `string` | – | After every figure: " hrs", " km". |
| `format` | `Intl.NumberFormatOptions` | `{ maximumFractionDigits: 1 }` | How totals and bars read. |
| `locales` | `string \| string[]` | – | For number formatting. |
| `tone` | `"cobalt" \| "ember" \| "rose" \| "emerald" \| "midnight" \| "violet" \| string` | `"cobalt"` | The lacquer’s colour. |
| `accent` | `string` | `"#dcfc4e"` | The marker and the up pill. |

## States

- **point**: The pillar under a mouse, a tap or the arrow keys crossfades to white over 200ms; the marker glides above it (380ms, slight overshoot) and the line under the total morphs.
- **range**: The switch’s pill slides (420ms). The pillars on show sink 10px and fade over 260ms; the new ones rise from the floor over 720ms, 42ms apart, from the side you moved toward; the curve draws in over 900ms; the total and change roll.
- **resize**: The marker and the curve follow the pillars when the card changes width.
- **reduced motion**: No rise, sink, draw or roll: everything changes in place.

## What it handles

A plain bar card snaps when the range changes and gives no feel for which day you’re reading.

- **Your data**: Ranges of bars in your own units; heights scale to each range’s tallest.
- **Ranges**: A sliding switch; the pillars sink and rise in a wave the way you moved.
- **Reading a pillar**: Point, tap or arrow to it: it turns white and the line says what it is.
- **Rolling figures**: The total and the change roll; the change pill says up or down.
- **Any colour**: Named lacquer tones or any CSS colour, always a dark finish.
- **Screen readers**: A hidden table of every pillar, and the pillars as a group of radios.

## Replaces

weekly bar chart, stat card chart, activity chart, screen time chart, range toggle chart

## Where it fits

- **Productivity**: Focus or screen time across a week, a month and a year.
- **Fitness**: Distance, workouts or active minutes, with the change against last period.
- **Creative tools**: Hours in the studio, words written, tracks finished.
- **Wallets and usage**: Spend or usage per day, as a stat card on a dashboard.

## Notes

- Always dark: the lacquer is the card’s own finish (colour pooled from two corners over near black, a fine light on the top edge, no drop shadow), so it reads the same on any page and needs no light version.
- Pillars move with transforms inside rounded clips, never by height, so a range change never relays out the card; the marker and curve are measured from the pillars once, and again on resize.
- The pillars are a radio group (one tab stop, arrows, Home and End); a hidden table lists every pillar with its value.
- Reduced motion drops the rise, sink, draw and roll.

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