# Dot meter

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

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.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/dot-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`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/dot-meter
- Registry item (source): https://hairlineui.com/r/dot-meter.json

## 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" },
  ]}
/>
```

## Plan usage on a billing page

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

```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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `DotMeterItem[]` | – | Each goal: key, label, value, goal, and optionally unit, color (any CSS colour) and icon. |
| `title` | `string` | `"Today"` | Over the fields. |
| `total / totalUnit` | `number / string` | – | A headline figure beside the title, e.g. the day’s calories. It rolls. |
| `columns / rows` | `number` | `8 / 5` | 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. |

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

## What it handles

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.

- **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.
- **Grains, not stretching**: New dots fall in and settle; fewer lift out from the top; only the change moves.
- **Over the goal, calmly**: A second lap of dots in ink falls onto the first instead of a red warning.
- **Point to compare**: The other goals dim and the name morphs into its share of the goal.
- **Colours from your theme**: Your chart colours in turn, or any colour per goal, with an icon if you like.
- **Accessible by default**: Each goal is a focusable meter with its value and goal in words.

## Replaces

a progress bar, a waffle chart, a goal tracker, a macro tracker, a quota meter, a legend

## Where it fits

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

## Notes

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

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