Skip to content
Browse documentation

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.

Used forCash flowCaloriesBudget against actualCapacity

Install with the shadcn CLI

$ npx shadcn@latest add https://hairlineui.com/r/balance-meter.json

Registered the namespace? Then it’s shadcn add @hairline/balance-meter. Set it up

Templates

Need the whole page?

61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.

All 61 templates

Where it’s used

  • 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.

What it handles for you

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.

Instead of wiring upa diverging bara net figurea gaugea surplus/deficit indicatora variance chart
  1. Size, not only sign

    The net is a run of lit ticks from zero, so you see how big it is against the scale.

  2. A needle that settles

    It swings to the new net on a spring and settles; the ticks it passes fade slowly.

  3. 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.

  4. Both flows in view

    The net with its sign, beside what came in and what went out.

  5. Colours from your theme

    Two chart colours by default, read again when the theme changes.

  6. Accessible by default

    The scale is a meter whose value reads out with both flows.

Overview

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.

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.

Usage

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 }}/>

Works with

Calories in a fitness app

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

example.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

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= "Net"
string
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.

Accessibility and motion

  • 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.

Requirements

React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

The CLI also installs Number roll.

Source

"use client";import * as React from "react";import { NumberRoll } from "./number-roll";import { createSpring, type Spring } from "./ui-interaction-motion";/* ───────────────────────────────────────────────────────── * BALANCE METER: what came in against what went out, and the net * *   scale     a row of upright hairline ticks centred on zero; the *             ticks from zero to the net light in the colour of the *             side that's ahead, brighter toward the needle *   settle    when the numbers change the needle swings to the new *             net on a spring and settles like a scale's pointer; *             the ticks it sweeps over keep a little light and let *             it go slowly behind it *   range     the scale picks round limits for you; when they *             change, the labels roll to the new ones * * One canvas draws the ticks and the needle; it redraws only while * the needle moves or the light fades, and takes the theme's colours. * ───────────────────────────────────────────────────────── */export interface BalanceFlow {  label: string;  value: number;  /** Any CSS colour. Inflow defaults to --chart-1, outflow to --chart-2. */  color?: string;  icon?: React.ReactNode;}export interface BalanceMeterProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {  /** What came in: money in, calories eaten, capacity added. The net is inflow minus outflow. */  inflow: BalanceFlow;  /** What went out: money out, calories burned, capacity used. */  outflow: BalanceFlow;  /** The scale's limit either side of zero. Picked from the numbers when left out. */  range?: number;  title?: string;  unit?: string;  format?: Intl.NumberFormatOptions;  locales?: string | string[];}const EASE = "cubic-bezier(0.16,1,0.3,1)";const PITCH = 5; // one tick every 5pxconst TICK = 2;const H = 40; // the canvasconst PAD = 16; // room for the end labels to sit centred under their ticksconst AFTERGLOW = 900; // ms for the light a passing needle leaves to fade to a thirdconst reducedQuery = "(prefers-reduced-motion: reduce)";const subscribeReduced = (onChange: () => void) => {  const query = window.matchMedia(reducedQuery);  query.addEventListener("change", onChange);  return () => query.removeEventListener("change", onChange);};const useReducedMotion = () =>  React.useSyncExternalStore(subscribeReduced, () => window.matchMedia(reducedQuery).matches, () => false);const subscribeNothing = () => () => {};const useHydrated = () => React.useSyncExternalStore(subscribeNothing, () => true, () => false);/** A round limit a little past what's shown: 1, 2, 2.5 or 5 times a power of ten. */function niceRange(net: number, inflow: number, outflow: number) {  const want = Math.max(Math.abs(net) * 1.4, (Math.abs(inflow) + Math.abs(outflow)) * 0.12, 1);  const power = 10 ** Math.floor(Math.log10(want));  for (const step of [1, 2, 2.5, 5, 10]) if (step * power >= want) return step * power;  return 10 * power;}interface Engine {  width: number;  half: number;  needle: Spring | null;  last: number;  glow: Float32Array;  glowSide: Int8Array;  frame: number;  time: number;  colors: { inflow: string; outflow: string; ink: string; bg: string };}/** One frame: the faint field, the lit run from zero to the needle, the light the needle left behind, and the needle. */function draw(e: Engine, canvas: HTMLCanvasElement | null) {  if (!canvas || !e.width || !e.needle) return;  const ctx = canvas.getContext("2d");  if (!ctx) return;  const dpr = Math.min(window.devicePixelRatio || 1, 2);  const w = e.width;  if (canvas.width !== Math.round(w * dpr)) {    canvas.width = Math.round(w * dpr);    canvas.height = Math.round(H * dpr);  }  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);  ctx.clearRect(0, 0, w, H);  const now = performance.now();  const dt = e.time ? Math.min(now - e.time, 100) : 0;  e.time = now;  const fade = Math.exp(-dt / (AFTERGLOW / Math.log(3)));  const half = e.half;  const cx = w / 2;  const pos = Math.max(-1.04, Math.min(1.04, e.needle.get())) * half; // in ticks  // The ticks the needle crossed since the last frame keep its light.  const lo = Math.min(pos, e.last);  const hi = Math.max(pos, e.last);  let glowing = false;  for (let k = -half; k <= half; k++) {    const i = k + half;    e.glow[i] *= fade;    if (k !== 0 && k >= Math.ceil(lo) && k <= Math.floor(hi) && hi - lo > 0.05) {      e.glow[i] = 1;      e.glowSide[i] = k > 0 ? 1 : -1;    }    if (e.glow[i] > 0.01) glowing = true;    else e.glow[i] = 0;  }  e.last = pos;  const base = H - 6;  for (let k = -half; k <= half; k++) {    const i = k + half;    const x = cx + k * PITCH - TICK / 2;    const major = k === 0 ? 2 : k % (half / 2) === 0 ? 1 : 0;    const h = major === 2 ? 26 : major === 1 ? 19 : 13;    // Faint field    ctx.globalAlpha = major === 2 ? 0.42 : major === 1 ? 0.24 : 0.13;    ctx.fillStyle = e.colors.ink;    const lit = k !== 0 && (k > 0 ? k <= pos : k >= pos) && Math.abs(pos) > 0.01;    const light = lit ? 0.32 + 0.68 * Math.min(1, Math.abs(k) / Math.max(1, Math.abs(pos))) ** 1.4 : 0;    const after = e.glow[i] * 0.55;    if (light <= 0 && after <= 0) {      ctx.fillRect(x, base - h, TICK, h);      continue;    }    const side = lit ? (k > 0 ? 1 : -1) : e.glowSide[i];    ctx.globalAlpha = Math.max(light, after);    ctx.fillStyle = side > 0 ? e.colors.inflow : e.colors.outflow;    ctx.fillRect(x, base - h, TICK, h);  }  // The needle, with a gap of the card's colour cut round it so it reads over the ticks.  const nx = cx + pos * PITCH;  ctx.globalAlpha = 1;  ctx.fillStyle = e.colors.bg;  ctx.fillRect(nx - 3.5, 0, 7, H);  ctx.fillStyle = e.colors.ink;  ctx.beginPath();  ctx.roundRect(nx - 1.25, 3, 2.5, H - 6, 1.25);  ctx.fill();  ctx.beginPath();  ctx.arc(nx, 4.5, 3.5, 0, Math.PI * 2);  ctx.fill();  const moving = e.needle.getVelocity() !== 0;  if (glowing && !moving && !e.frame) {    e.frame = requestAnimationFrame(() => {      e.frame = 0;      draw(e, canvas);    });  }  if (!glowing && !moving) e.time = 0;}export function BalanceMeter({ inflow, outflow, range: rangeProp, title = "Net", unit, format, locales, className = "", ...props }: BalanceMeterProps) {  const reduced = useReducedMotion();  const hydrated = useHydrated();  const locale = locales ?? (hydrated ? undefined : "en-US");  const net = inflow.value - outflow.value;  const range = rangeProp ?? niceRange(net, inflow.value, outflow.value);  const inColor = inflow.color ?? "var(--chart-1, var(--primary))";  const outColor = outflow.color ?? "var(--chart-2, var(--primary))";  const [visible, setVisible] = React.useState(false);  const [width, setWidth] = React.useState(0);  const rootRef = React.useRef<HTMLDivElement>(null);  const boxRef = React.useRef<HTMLDivElement>(null);  const canvasRef = React.useRef<HTMLCanvasElement>(null);  const probes = React.useRef<(HTMLSpanElement | null)[]>([]);  const engine = React.useRef<Engine>({    width: 0,    half: 0,    needle: null,    last: 0,    glow: new Float32Array(0),    glowSide: new Int8Array(0),    frame: 0,    time: 0,    colors: { inflow: "#305dde", outflow: "#e8743b", ink: "#454545", bg: "#fff" },  });  const paint = React.useCallback(() => draw(engine.current, canvasRef.current), []);  // The needle's spring, made before anything paints.  React.useLayoutEffect(() => {    const e = engine.current;    // A little under critical damping: it swings past and settles, like a scale's pointer.    e.needle = createSpring(0, { stiffness: 150, damping: 15 }, paint, 0.0005);    return () => {      e.needle?.stop();      e.needle = null;      if (e.frame) cancelAnimationFrame(e.frame);      e.frame = 0;    };  }, [paint]);  React.useLayoutEffect(() => {    const box = boxRef.current;    if (!box) return;    const measure = () => setWidth((w) => (w === box.offsetWidth ? w : box.offsetWidth));    measure();    const observer = new ResizeObserver(measure);    observer.observe(box);    return () => observer.disconnect();  }, []);  // Ticks to fit the width, an even number either side so the half-way ticks land on whole ticks.  const half = Math.max(4, Math.floor((width - PAD * 2) / PITCH / 4) * 2);  React.useLayoutEffect(() => {    const e = engine.current;    e.width = width;    if (e.half !== half) {      e.half = half;      e.glow = new Float32Array(half * 2 + 1);      e.glowSide = new Int8Array(half * 2 + 1);      e.last = (e.needle?.get() ?? 0) * half;    }    paint();  }, [width, half, paint]);  // The theme's colours, read again whenever the theme changes.  React.useEffect(() => {    const read = () => {      const [a, b, c, d] = probes.current.map((p) => (p ? getComputedStyle(p).color : ""));      engine.current.colors = { inflow: a || "#305dde", outflow: b || "#e8743b", ink: c || "#454545", bg: d || "#fff" };      paint();    };    read();    const observer = new MutationObserver(read);    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "style", "data-theme"] });    const media = window.matchMedia("(prefers-color-scheme: dark)");    media.addEventListener("change", read);    return () => {      observer.disconnect();      media.removeEventListener("change", read);    };  }, [inColor, outColor, paint]);  React.useEffect(() => {    const el = rootRef.current;    if (!el) return;    const observer = new IntersectionObserver(      ([entry]) => {        if (entry.isIntersecting) {          setVisible(true);          observer.disconnect();        }      },      { rootMargin: "0px 0px -10% 0px" },    );    observer.observe(el);    return () => observer.disconnect();  }, []);  const target = visible ? net / range : 0;  React.useEffect(() => {    const needle = engine.current.needle;    if (!needle) return;    if (reduced) needle.jump(target);    else needle.set(target);  }, [target, reduced]);  const fmt = (v: number) => new Intl.NumberFormat(locale, format).format(v);  const signed: Intl.NumberFormatOptions = { ...format, signDisplay: "exceptZero" };  const unitText = unit ? ` ${unit}` : "";  // Five labels where they fit, the ends and zero where they don't.  const marks = half * PITCH * 2 >= 300 ? [-1, -0.5, 0, 0.5, 1] : [-1, 0, 1];  const low = -range;  return (    <div ref={rootRef} className={`w-full rounded-[22px] bg-background shadow-[0_0_0_1px_var(--border)] ${className}`} {...props}>      <div aria-hidden="true" data-natural-width className="grid h-0" style={{ gridTemplateColumns: "minmax(0, 460px)" }} />      <div className="@container w-full">        <div className="p-4 @md:p-5">          <div className="flex flex-wrap items-end justify-between gap-x-4 gap-y-3">            <div className="min-w-0">              <p className="text-[26px] font-medium leading-none tracking-[-0.035em] text-foreground tabular-nums @md:text-[32px]">                <NumberRoll value={visible ? net : 0} format={signed} locales={locale} duration={1000} />                {unit && <span className="ml-1 text-[14px] font-normal tracking-normal text-muted-foreground @md:text-[15px]">{unit}</span>}              </p>              <p className="mt-1.5 truncate text-[12px] text-muted-foreground @md:text-[13px]">{title}</p>            </div>            <dl className="flex items-baseline gap-x-4 text-[12px] @md:text-[13px]">              {[outflow, inflow].map((flow, i) => {                const color = i === 0 ? outColor : inColor;                return (                  <div key={i} className="flex items-baseline gap-1.5">                    <dt className="flex items-center gap-1.5 self-center text-muted-foreground">                      {flow.icon ? (                        <span className="flex size-3.5 items-center justify-center [&>svg]:size-3.5" style={{ color }}>                          {flow.icon}                        </span>                      ) : (                        <span className="size-2 rounded-[2px]" style={{ background: color }} />                      )}                      {flow.label}                    </dt>                    <dd className="font-medium tabular-nums" style={{ color: `color-mix(in oklab, ${color} 82%, var(--foreground))` }}>                      <NumberRoll value={visible ? flow.value : 0} format={format} locales={locale} duration={1000} />                    </dd>                  </div>                );              })}            </dl>          </div>          <div            ref={boxRef}            role="meter"            aria-label={title}            aria-valuemin={low}            aria-valuemax={range}            aria-valuenow={net}            aria-valuetext={`${new Intl.NumberFormat(locale, signed).format(net)}${unitText}: ${inflow.label} ${fmt(inflow.value)}, ${outflow.label} ${fmt(outflow.value)}`}            className="relative mt-5 @md:mt-6"          >            <canvas ref={canvasRef} aria-hidden="true" className="block w-full" style={{ height: H }} />            <div aria-hidden="true" className="relative mt-1.5 h-4 text-[11px] text-muted-foreground tabular-nums @md:text-[11.5px]">              {width > 0 &&                marks.map((m) => (                  <span                    key={m}                    className="absolute top-0 -translate-x-1/2 whitespace-nowrap"                    style={{ left: width / 2 + m * half * PITCH, transition: `left 300ms ${EASE}` }}                  >                    <NumberRoll value={m * range} format={format} locales={locale} duration={reduced ? 0 : 900} />                  </span>                ))}            </div>          </div>        </div>      </div>      {/* Colour probes for the canvas. */}      <span ref={(el) => void (probes.current[0] = el)} aria-hidden="true" className="hidden" style={{ color: inColor }} />      <span ref={(el) => void (probes.current[1] = el)} aria-hidden="true" className="hidden" style={{ color: outColor }} />      <span ref={(el) => void (probes.current[2] = el)} aria-hidden="true" className="hidden text-foreground" />      <span ref={(el) => void (probes.current[3] = el)} aria-hidden="true" className="hidden text-background" />    </div>  );}

Registry item: /r/balance-meter.json