# Spending ring

> Where the money went, and what is inside it: thick tiles with their amounts on them, and a category that blooms open into a ring of its own.

A ring of spending categories for a banking, budgeting or analytics screen that reads on its own. Each category is a thick tile of the ring with its amount written on it, and the total sits large in the middle, so there is no legend to match colours against. Point at a tile (or tab to it) and it slides out while the others turn to the muted surface; the centre label morphs to it and the total rolls to its amount. Click a category and its tile splits into its parts, then blooms open from where it sits, pushing the others out of the ring until it is the whole ring: Food becomes Groceries, Dining and Coffee, and the centre rolls to Food's total. "All" or Escape folds it home. The overspent end of a tile is hatched in red.

## Install

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

## Usage

```tsx
import { SpendingRing } from "@/components/spending-ring";

<SpendingRing
  label="Spent in October"
  format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
  data={[
    { id: "food", label: "Food", value: 612, budget: 550, children: [
      { id: "groceries", label: "Groceries", value: 342 },
      { id: "restaurants", label: "Restaurants", value: 188 },
    ] },
    { id: "home", label: "Home", value: 1450 },
  ]}
/>
```

## Open into merchants from your API

Keep the open category in your state (or the URL) and load what it is made of when it opens. Until the parts arrive the category simply has none, so it does not open.

```tsx
"use client";
import * as React from "react";
import { SpendingRing, type SpendCategory } from "@/components/spending-ring";

export function MonthSpending({ month, categories }: { month: string; categories: SpendCategory[] }) {
  const [open, setOpen] = React.useState<string | null>(null);
  const [parts, setParts] = React.useState<Record<string, SpendCategory[]>>({});

  React.useEffect(() => {
    if (!open || parts[open]) return;
    fetch(`/api/spending/${month}/${open}`)
      .then((res) => res.json())
      .then((list: SpendCategory[]) => setParts((all) => ({ ...all, [open]: list })));
  }, [open, month, parts]);

  return (
    <SpendingRing
      label={`Spent in ${month}`}
      format={{ style: "currency", currency: "EUR" }}
      open={open}
      onOpenChange={setOpen}
      data={categories.map((c) => ({ ...c, children: parts[c.id] ?? c.children }))}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `SpendCategory[]` | – | { id, label, value, budget?, color?, children? }. Categories with children open into their own ring. |
| `label` | `string` | `"Spent"` | Above the total while nothing is open or pointed at. |
| `format / locales` | `Intl.NumberFormatOptions / string \| string[]` | – | How amounts are written, e.g. { style: "currency", currency: "USD" }. |
| `open / defaultOpen / onOpenChange` | `string \| null` | – | The open category's id, controlled or not. |
| `size` | `number` | `256` | Ring diameter in px. |
| `thickness` | `number` | `42` | Ring thickness in px. Amounts show on tiles thicker than 30px. |
| `legend` | `boolean` | `false` | Also list the categories under the ring. |

## States

- **overview**: Thick tiles in order from the top with 5px gaps and 7px corners, each with its amount on it when it fits; the label and the total in the middle.
- **point**: Pointing at a tile or tabbing to it slides it 5px outward and turns the others to the muted surface (colour, not opacity, so their amounts stay legible); the centre label morphs and the total rolls to its amount, with its share or budget under it.
- **opening**: The tile splits into its parts in shades of its colour, then blooms from its middle to the whole ring while the others are squeezed out and fade; the parts' amounts fade in as they find room, and the centre rolls to the category.
- **open**: The parts fill the ring; pointing works the same. "All" in the centre, or Escape, folds it back home the same way in reverse.
- **over budget**: The overspent share of a tile, at its end, is hatched in red; pointing at it says "$84 over budget" in the centre.
- **reduced motion**: Opening, closing and pointing switch at once; the figures still change.

## What it handles

A donut shows the split but not what is inside it; drilling in usually means a second chart that replaces the first with no sense of where you went.

- **You see where you went**: The category you open grows into the whole ring from where it sat, so its parts are visibly what it was made of, and Back folds it home.
- **Turn back mid-way**: Every angle comes from one spring, so pressing Back or another category during the bloom reverses it from where it is.
- **Reads without a legend**: Every tile carries its own amount, in black or white to suit its colour, and the total is the largest thing on it.
- **Budgets in place**: The overspent end of a tile is hatched in red, and the centre says "$84 over budget" when you point at it.
- **Keyboard and screen readers**: Tiles are buttons with their name, amount and share: Tab points, Enter opens, Escape goes back.
- **Your data, your format**: Pass categories with children and any Intl number format; colours default to your chart tokens and parts take shades of their category.

## Replaces

drill down pie chart, sunburst chart, nested donut chart, recharts pie drilldown, budget donut

## Where it fits

- **Banking home**: This month's spending by category, opening into merchants or sub-categories.
- **Budgets**: Categories against their budgets, with the overspend marked on the ring and in the list.
- **Cloud and SaaS costs**: Spend by service, opening into projects or resources.
- **Expense reports**: A team's spending by type, opening into people or cost centres.

## Notes

- Each tile is a button labelled with its name, amount and share, and says when it opens; Tab points at it, Enter opens it, Escape folds home.
- Amounts on tiles pick black or white from the tile's own lightness (relative oklch colour), so they read in light and dark and on your own colours.
- Colours default to --chart-1 to --chart-5; parts take lighter and darker steps of their category colour.
- Only path shapes, fills and transforms change while it moves, from one spring for opening and one per tile for pointing; nothing re-renders per frame.

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