# Balance meter

> What came in against what went out, and the net on a scale of hairline ticks whose needle swings and settles like a scale’s pointer.

Net figures are usually a number in green or red, which says the sign but not how big it is against the flows behind it. Balance meter puts the net on a scale centred on zero, drawn as a row of upright hairline ticks. The ticks from zero to the net light up in the colour of the side that is ahead, brighter toward the needle, so a small surplus is a short faint run and a big one a long bright one. When the numbers change the needle swings to the new net on a spring and settles with a small overshoot, like the pointer of a kitchen scale, and the ticks it sweeps over keep a little of its light and let it go slowly behind it. The scale picks round limits for you; when they change, the labels under it roll to the new ones. Above it the net rolls with its sign, beside the two flows in their colours.

## Install

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

## Usage

```tsx
import { BalanceMeter } from "@/components/balance-meter";

<BalanceMeter
  title="Net cash flow"
  inflow={{ label: "In", value: 12480 }}
  outflow={{ label: "Out", value: 9860 }}
  format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
/>
```

## Calories in a fitness app

The same meter for energy: eaten is the inflow, burned the outflow, with a fixed scale of ±500.

```tsx
import { BalanceMeter } from "@/components/balance-meter";
import { Apple, Flame } from "lucide-react";

export function EnergyCard({ eaten, burned }: { eaten: number; burned: number }) {
  return (
    <BalanceMeter
      title="Net energy"
      unit="kcal"
      range={500}
      inflow={{ label: "Eaten", value: eaten, icon: <Apple /> }}
      outflow={{ label: "Burned", value: burned, icon: <Flame /> }}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inflow` | `{ label, value, color?, icon? }` | – | What came in. The net is inflow minus outflow, lit to the right of zero. |
| `outflow` | `{ label, value, color?, icon? }` | – | What went out, lit to the left of zero when it’s ahead. |
| `range` | `number` | – | The scale’s limit either side of zero. Picked as a round number from the figures when left out. |
| `title` | `string` | `"Net"` | Under the net figure. |
| `unit` | `string` | – | After the net figure, e.g. "kcal". |
| `format` | `Intl.NumberFormatOptions` | – | How every figure is written; the net also shows its sign. |
| `locales` | `string \| string[]` | – | The locale for the figures; the visitor’s once hydrated when left out. |

## States

- **arrive**: In view for the first time, the needle swings out from zero to the net, the ticks behind it lighting, and every figure rolls up.
- **settle**: A new net sends the needle on a spring a little under critical damping (stiffness 150, damping 15): it passes the mark by about a tenth and settles. Ticks it crosses keep its light and fade to a third in 0.9s.
- **lit run**: Ticks between zero and the needle are in the leading side’s colour, from a third of full strength at zero to full at the needle.
- **rescale**: When the round limit changes, the labels (five, or the ends and zero on a narrow card) roll to the new values (900ms) and the needle moves to its new place on the new scale.
- **reduced motion**: The needle jumps to the net with no swing or trail; figures change in place.

## What it handles

A net figure in green or red tells the sign but not the size, and a pair of bars for in and out makes you do the subtraction yourself.

- **Size, not only sign**: The net is a run of lit ticks from zero, so you see how big it is against the scale.
- **A needle that settles**: It swings to the new net on a spring and settles; the ticks it passes fade slowly.
- **Round limits for you**: The scale picks 1, 2, 2.5 or 5 times a power of ten, and its labels roll when it changes.
- **Both flows in view**: The net with its sign, beside what came in and what went out.
- **Colours from your theme**: Two chart colours by default, read again when the theme changes.
- **Accessible by default**: The scale is a meter whose value reads out with both flows.

## Replaces

a diverging bar, a net figure, a gauge, a surplus/deficit indicator, a variance chart

## Where it fits

- **Cash flow**: Money in against money out for a day, a week or a month.
- **Calories**: Eaten against burned, and the surplus or deficit, in a fitness app.
- **Budget against actual**: How far over or under plan a team or a category is.
- **Capacity**: Headroom left, or how far a cluster or a warehouse is over.

## Notes

- The scale is a role="meter" from minus to plus the range; its text reads the net with both flows.
- One canvas draws the ticks and the needle at your screen’s resolution. It redraws only while the needle moves or its trail fades, and reads your theme’s colours again when the theme changes.
- The needle runs on createSpring from ui-interaction-motion.ts, which installs with it.
- Installs Number roll. With reduced motion the needle jumps and leaves no trail.

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