Skip to content
Browse documentation

Several goals at once, each a small field of dots that pours in like grains: protein, carbs and fat, or seats, storage and API calls.

Used forNutrition and fitnessPlan quotasBudgetsTeam goals

Install with the shadcn CLI

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

Registered the namespace? Then it’s shadcn add @hairline/dot-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

  • Nutrition and fitness

    Protein, carbs and fat against the day’s goals.

  • Plan quotas

    Seats, storage and API calls used on a billing or usage page.

  • Budgets

    A few categories against this month’s budget in a finance app.

  • Team goals

    Deals, demos and calls against each target on a sales dashboard.

What it handles for you

A row of progress bars reads as a form: three thin lines of the same shape, where going over the goal is either clipped or shown in alarm red.

Instead of wiring upa progress bara waffle charta goal trackera macro trackera quota metera legend
  1. A picture per goal

    Each goal is a field of dots that stands for the whole of it, so a glance tells you how full it is.

  2. Grains, not stretching

    New dots fall in and settle; fewer lift out from the top; only the change moves.

  3. Over the goal, calmly

    A second lap of dots in ink falls onto the first instead of a red warning.

  4. Point to compare

    The other goals dim and the name morphs into its share of the goal.

  5. Colours from your theme

    Your chart colours in turn, or any colour per goal, with an icon if you like.

  6. Accessible by default

    Each goal is a focusable meter with its value and goal in words.

Overview

Goal cards usually show one progress bar per goal, and a row of three bars reads as a form, not a picture. Dot meter gives each goal a small field of dots, eight across and five down, that stands for the whole goal. As the value grows, new dots fall in from above like grains and settle bottom row first, each landing with a small bounce, so you watch the field fill rather than a bar stretch. A bigger value pours only the new grains onto the ones already there; a smaller one lifts the top grains out, last in first out. Past the goal a second lap of grains in ink falls onto the first, from the bottom again, so going over is visible without a red warning. Point at a goal, or focus it, and the others dim while its name morphs into its share of the goal. Under each field the figure rolls.

States

arrive
In view for the first time, each goal’s grains fall in from above and settle bottom row first, 16ms apart, one goal a beat (110ms) after another; the figures roll up.
grow
Only the new grains pour, 26ms apart, each falling from above the field with a small bounce as it lands (about 400–550ms by height).
shrink
The top grains lift out and shrink away, last in first out (280ms each, 18ms apart).
over
Past the goal, a second lap of grains in ink (your foreground with a trace of the colour) falls onto the first, from the bottom, once the first lap has landed.
point
Pointing at a goal (or focusing it) dims the others to 38% (200ms); its name morphs into its share of the goal, “105%”.
reduced motion
Grains appear and leave in place; nothing falls.

Usage

usage.tsx
import { DotMeter } from "@/components/dot-meter";<DotMeter  title="Today’s food"  total={1479}  totalUnit="kcal"  items={[    { key: "protein", label: "Protein", value: 78, goal: 120, unit: "g" },    { key: "carbs", label: "Carbs", value: 186, goal: 250, unit: "g" },    { key: "fat", label: "Fat", value: 47, goal: 70, unit: "g" },  ]}/>

Works with

Plan usage on a billing page

The same meter as quotas: read usage on the server and pass each limit as the goal.

example.tsx
import { DotMeter } from "@/components/dot-meter";import { HardDrive, KeyRound, Users } from "lucide-react";import { getUsage } from "@/lib/billing";export async function UsageCard({ teamId }: { teamId: string }) {  const u = await getUsage(teamId); // { seats, seatLimit, storageGb, storageLimitGb, calls, callLimit }  return (    <DotMeter      title="This month"      items={[        { key: "seats", label: "Seats", value: u.seats, goal: u.seatLimit, icon: <Users /> },        { key: "storage", label: "Storage", value: u.storageGb, goal: u.storageLimitGb, unit: "GB", icon: <HardDrive /> },        { key: "calls", label: "API calls", value: u.calls, goal: u.callLimit, icon: <KeyRound /> },      ]}      format={{ notation: "compact" }}    />  );}

Props

items
DotMeterItem[]
Each goal: key, label, value, goal, and optionally unit, color (any CSS colour) and icon.
title= "Today"
string
Over the fields.
total / totalUnit
number / string
A headline figure beside the title, e.g. the day’s calories. It rolls.
columns / rows= 8 / 5
number
Dots across and down in each field; together they stand for one goal.
format
Intl.NumberFormatOptions
How the figures are written.
locales
string | string[]
The locale for the figures; the visitor’s once hydrated when left out.

Accessibility and motion

  • Each goal is a role="meter" with its value and goal as text (“78 g of 120 g”) and can take focus, which shows its share.
  • Every grain is moved by transform, one Web Animation each, so nothing re-renders while they fall; the field is plain DOM that takes your theme in light and dark.
  • Dots are rounded to the nearest one: with 40 dots each stands for 2.5% of the goal.
  • Installs Number roll and Text morph. With reduced motion grains appear and leave in place.

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, Text morph.

Source

components/dot-meter.tsx
"use client";import * as React from "react";import { NumberRoll } from "./number-roll";import { TextMorph } from "./text-morph";/* ───────────────────────────────────────────────────────── * DOT METER: several goals at once, each a small field of dots * *   arrive    each goal's dots pour in from above like grains and *             settle bottom row first, one goal after another *   grow      a bigger value pours only the new grains, from the *             top of the field down onto the ones already there *   shrink    the top grains lift out, last in first out *   over      past the goal a second, deeper lap of grains falls *             onto the first, from the bottom again *   point     point at (or focus) a goal and the others dim; its *             name becomes its share of the goal * * Every grain moves by transform only (one Web Animation each); * nothing re-renders while they fall. * ───────────────────────────────────────────────────────── */export interface DotMeterItem {  key: string;  label: string;  value: number;  goal: number;  /** Shown after the figures, e.g. "g" or "GB". */  unit?: string;  /** Any CSS colour. Defaults to your chart colours in turn. */  color?: string;  /** A small icon before the name. */  icon?: React.ReactNode;}export interface DotMeterProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {  items: DotMeterItem[];  title?: string;  /** A headline figure beside the title, e.g. today's calories. */  total?: number;  totalUnit?: string;  /** Dots across and down in each field; together they stand for one goal. */  columns?: number;  rows?: number;  format?: Intl.NumberFormatOptions;  locales?: string | string[];}const EASE = "cubic-bezier(0.16,1,0.3,1)";const FOCUS = "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40 focus-visible:ring-offset-4 focus-visible:ring-offset-background";const GAP = 3;const 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);// Formatting waits for hydration: the server and the hydrating render share one fixed locale, then the visitor's takes over.const subscribeNothing = () => () => {};const useHydrated = () => React.useSyncExternalStore(subscribeNothing, () => true, () => false);const mix = (color: string, amount: number, into = "transparent") => `color-mix(in oklab, ${color} ${amount}%, ${into})`;export function DotMeter({  items,  title = "Today",  total,  totalUnit,  columns = 8,  rows = 5,  format,  locales,  className = "",  ...props}: DotMeterProps) {  const reduced = useReducedMotion();  const hydrated = useHydrated();  const locale = locales ?? (hydrated ? undefined : "en-US");  const [visible, setVisible] = React.useState(false);  const [active, setActive] = React.useState<string | null>(null);  const rootRef = React.useRef<HTMLDivElement>(null);  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 fmt = (v: number) => new Intl.NumberFormat(locale, format).format(v);  return (    <div ref={rootRef} className={`w-full rounded-[22px] bg-background shadow-[0_0_0_1px_var(--border)] ${className}`} {...props}>      {/* Its natural width where the parent sizes to its content (a centred flex column), without forcing it on narrow screens. */}      <div aria-hidden="true" data-natural-width className="grid h-0" style={{ gridTemplateColumns: "minmax(0, 440px)" }} />      <div className="@container w-full">        <div className="p-4 @md:p-5">          <div className="flex items-baseline justify-between gap-3">            <p className="truncate text-[12.5px] text-muted-foreground @md:text-[13px]">{title}</p>            {total !== undefined && (              <p className="shrink-0 text-[15px] font-medium tracking-[-0.02em] text-foreground tabular-nums @md:text-[17px]">                <NumberRoll value={visible ? total : 0} format={format} locales={locale} duration={1100} />                {totalUnit && <span className="ml-1 text-[12px] font-normal tracking-normal text-muted-foreground @md:text-[13px]">{totalUnit}</span>}              </p>            )}          </div>          <div            className="mt-4 grid gap-x-4 @md:mt-5 @md:gap-x-6"            style={{ gridTemplateColumns: `repeat(${Math.max(1, items.length)}, minmax(0, 1fr))` }}            onPointerLeave={(e) => {              if (e.pointerType !== "touch") setActive(null);            }}          >            {items.map((item, i) => (              <Field                key={item.key}                item={item}                color={item.color ?? `var(--chart-${(i % 5) + 1}, var(--primary))`}                index={i}                columns={columns}                rows={rows}                visible={visible}                reduced={reduced}                dim={active !== null && active !== item.key}                pointed={active === item.key}                onPoint={setActive}                fmt={fmt}                format={format}                locale={locale}              />            ))}          </div>        </div>      </div>    </div>  );}interface FieldProps {  item: DotMeterItem;  color: string;  index: number;  columns: number;  rows: number;  visible: boolean;  reduced: boolean;  dim: boolean;  pointed: boolean;  onPoint: (key: string | null) => void;  fmt: (v: number) => string;  format?: Intl.NumberFormatOptions;  locale?: string | string[];}const Field = React.memo(function Field({ item, color, index, columns, rows, visible, reduced, dim, pointed, onPoint, fmt, format, locale }: FieldProps) {  const n = columns * rows;  const ratio = item.goal > 0 ? Math.max(0, item.value) / item.goal : 0;  const grains = Math.round(ratio * n);  // Before it's seen the field is empty, so the first pour is the arrival.  const first = visible ? Math.min(grains, n) : 0;  const second = visible ? Math.min(Math.max(grains - n, 0), n) : 0;  const gridRef = React.useRef<HTMLDivElement>(null);  const laps = React.useRef<(HTMLSpanElement | null)[][]>([[], []]);  const shown = React.useRef([0, 0]);  const arrived = React.useRef(false);  // Pour new grains in and lift old ones out, by fill order (bottom row first, left to right).  React.useLayoutEffect(() => {    const grid = gridRef.current;    if (!grid) return;    const targets = [first, second];    const cell = grid.firstElementChild as HTMLElement | null;    const pitch = (cell?.offsetHeight ?? 10) + GAP;    const opening = !arrived.current && first > 0;    if (opening) arrived.current = true;    // When both laps pour at once, the second waits for the first to land.    let landed = 0;    targets.forEach((target, lap) => {      const from = shown.current[lap];      if (target === from) return;      shown.current[lap] = target;      const els = laps.current[lap];      if (target > from) {        const count = target - from;        const step = Math.min(opening ? 16 : 26, 640 / count);        const wait = (opening ? index * 110 : 0) + (lap === 1 ? landed : 0);        if (lap === 0) landed = count * step + 420;        for (let i = from; i < target; i++) {          const el = els[i];          if (!el) continue;          el.getAnimations().forEach((a) => a.cancel());          el.style.opacity = "1";          if (reduced) continue;          const rowFromTop = rows - 1 - Math.floor(i / columns);          const drop = (rowFromTop + 1.6) * pitch;          const fall = 240 + 70 * Math.sqrt(rowFromTop + 1.6);          el.animate(            [              { transform: `translate3d(0,${-drop}px,0)`, opacity: 0, offset: 0, easing: "cubic-bezier(0.5,0,0.95,0.6)" },              { opacity: 1, offset: 0.3 },              { transform: "translate3d(0,0,0)", offset: 0.76, easing: "cubic-bezier(0.2,0.7,0.4,1)" },              { transform: `translate3d(0,${-Math.min(2, pitch * 0.18)}px,0)`, offset: 0.88, easing: "cubic-bezier(0.6,0,0.8,0.4)" },              { transform: "translate3d(0,0,0)", opacity: 1, offset: 1 },            ],            { duration: fall / 0.76, delay: wait + (i - from) * step, easing: "linear", fill: "backwards" },          );        }      } else {        const count = from - target;        const step = Math.min(18, 360 / count);        for (let i = from - 1; i >= target; i--) {          const el = els[i];          if (!el) continue;          el.getAnimations().forEach((a) => a.cancel());          el.style.opacity = "0";          if (reduced) continue;          el.animate(            [              { transform: "translate3d(0,0,0) scale(1)", opacity: 1 },              { transform: `translate3d(0,${-pitch * 0.9}px,0) scale(0.5)`, opacity: 0 },            ],            { duration: 280, delay: (from - 1 - i) * step, easing: EASE, fill: "backwards" },          );        }      }    });  }, [first, second, columns, rows, index, reduced]);  const unit = item.unit ? ` ${item.unit}` : "";  const share = Math.round(ratio * 100);  // Short enough for the narrowest field: the share alone, in the goal's colour.  const caption = pointed ? `${share}%` : item.label;  // The second lap is ink with a trace of the colour: darker in light, lighter in dark, never a muddy shade of it.  const deep = mix(color, 30, "var(--foreground)");  // The DOM lists the field top-down; fill order counts from the bottom-left.  const cells = [];  for (let p = 0; p < n; p++) {    const fromTop = Math.floor(p / columns);    const i = (rows - 1 - fromTop) * columns + (p % columns);    cells.push(      <span key={p} className="relative aspect-square rounded-full" style={{ background: mix(color, 17) }}>        <span          ref={(el) => {            laps.current[0][i] = el;          }}          className="absolute inset-0 rounded-full opacity-0"          style={{ background: color, willChange: "transform" }}        />        <span          ref={(el) => {            laps.current[1][i] = el;          }}          className="absolute inset-0 rounded-full opacity-0"          style={{ background: deep, willChange: "transform" }}        />      </span>,    );  }  return (    <div      role="meter"      tabIndex={0}      aria-label={item.label}      aria-valuemin={0}      aria-valuemax={item.goal}      aria-valuenow={item.value}      aria-valuetext={`${fmt(item.value)}${unit} of ${fmt(item.goal)}${unit}`}      onPointerMove={(e) => {        if (e.pointerType === "mouse") onPoint(item.key);      }}      onPointerDown={() => onPoint(pointed ? null : item.key)}      onFocus={() => onPoint(item.key)}      onBlur={() => onPoint(null)}      className={`min-w-0 cursor-default rounded-[6px] outline-none transition-opacity duration-200 ${FOCUS}`}      style={{ opacity: dim ? 0.38 : 1, transitionTimingFunction: EASE }}    >      <div ref={gridRef} aria-hidden="true" className="grid max-w-[132px]" style={{ gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`, gap: GAP }}>        {cells}      </div>      <p className="mt-2.5 text-[15px] font-medium leading-tight tracking-[-0.02em] text-foreground tabular-nums @md:text-[17px]">        <NumberRoll value={visible ? item.value : 0} format={format} locales={locale} duration={1000} />        {item.unit && <span className="ml-0.5 text-[12px] font-normal tracking-normal text-muted-foreground @md:text-[13px]">{item.unit}</span>}      </p>      <p className="mt-0.5 flex min-w-0 items-center gap-1.5 text-[11.5px] text-muted-foreground @md:text-[12.5px]">        {item.icon ? (          <span className="flex size-3.5 shrink-0 items-center justify-center [&>svg]:size-3.5" style={{ color }}>            {item.icon}          </span>        ) : (          <span className="size-2 shrink-0 rounded-[2px]" style={{ background: color }} />        )}        <span className="min-w-0 truncate whitespace-nowrap">          <TextMorph>{caption}</TextMorph>        </span>      </p>    </div>  );});

Registry item: /r/dot-meter.json