# Animated Meter for UI SDK (/docs/components/meter)

The bar springs to its value, changes colour at thresholds and the digits roll.

```tsx title="example.tsx"
import * as React from "react"

import { Meter, MeterIndicator, MeterLabel, MeterTrack, MeterValue } from "@/components/keyframery/meter"

const key =
  "inline-flex h-8 cursor-pointer items-center rounded-[9px] bg-background px-3 text-[13px] leading-none font-medium text-foreground outline-none select-none shadow-[0_0_0_1px_rgb(0_0_0/0.06),0_1px_1px_rgb(0_0_0/0.05),0_3px_6px_-2px_rgb(0_0_0/0.1)] transition-[translate,scale,box-shadow] duration-100 active:translate-y-px active:scale-[0.985] focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-card dark:bg-accent dark:shadow-[0_0_0_1px_rgb(255_255_255/0.07),inset_0_1px_0_rgb(255_255_255/0.08),0_2px_6px_-1px_rgb(0_0_0/0.6)] motion-reduce:transition-none"

const gb = { style: "unit", unit: "gigabyte", maximumFractionDigits: 1 } as const

export default function MeterDemo() {
  const [cleaned, setCleaned] = React.useState(false)
  const videos = cleaned ? 3.6 : 12.4
  const used = 31.2 + videos + 3.7

  const rows = [
    { name: "Photos", size: 31.2 },
    { name: "Videos", size: videos },
    { name: "Documents", size: 3.7 },
  ]

  return (
    <div className="w-[400px]">
      <div className="flex items-baseline justify-between gap-4">
        <h3 className="text-[15px] font-semibold tracking-tight">Storage</h3>
        <p className="text-[12px] text-muted-foreground">Family plan</p>
      </div>
      <p className="mt-1 text-[13px] text-muted-foreground">
        {cleaned ? "Plenty of room for this summer’s photos" : "Almost full. New photos may stop syncing."}
      </p>

      <div className="mt-4 rounded-[14px] bg-card p-4 shadow-[0_0_0_1px_rgb(0_0_0/0.07),0_1px_2px_rgb(0_0_0/0.04)] dark:shadow-[0_0_0_1px_rgb(255_255_255/0.08)]">
        <Meter value={used} max={50} high={45} format={gb}>
          <MeterLabel>Used of 50 GB</MeterLabel>
          <MeterValue />
          <MeterTrack>
            <MeterIndicator />
          </MeterTrack>
        </Meter>

        <ul className="mt-4 space-y-3">
          {rows.map((row) => (
            <li key={row.name}>
              <Meter value={row.size} max={50} format={gb} className="gap-y-1.5">
                <MeterLabel className="font-normal text-muted-foreground">{row.name}</MeterLabel>
                <MeterValue className="text-[12px]" />
                <MeterTrack className="h-1">
                  <MeterIndicator className="bg-foreground/45" />
                </MeterTrack>
              </Meter>
            </li>
          ))}
        </ul>

        <div className="mt-5 flex items-center justify-between gap-3">
          <span className="text-[12px] text-muted-foreground tabular-nums">
            {cleaned ? "4 videos moved to your computer" : "4 videos over 2 GB"}
          </span>
          <button type="button" data-play="toggle" className={key} onClick={() => setCleaned((c) => !c)}>
            {cleaned ? "Undo" : "Free up 8.8 GB"}
          </button>
        </div>
      </div>
    </div>
  )
}
```

## Installation [#installation]

```bash
npx shadcn@latest add @keyframery/meter
```

This adds `components/keyframery/meter.tsx` and its primitive, `components/keyframery/primitives/meter.tsx`, to your project, and installs `@ui-sdk/react`. The motion tokens are added to your global CSS the first time you install a component.

## Usage [#usage]

```tsx
import {
  Meter,
  MeterIndicator,
  MeterLabel,
  MeterTrack,
  MeterValue,
} from "@/components/keyframery/meter"
```

The parts and props are the same as UI SDK's Meter. For every prop, see the [UI SDK meter reference](https://ui-sdk.dev/docs/components/meter).

## What moves [#what-moves]

| Move       | What you see                                                 |
| ---------- | ------------------------------------------------------------ |
| **Spring** | The bar springs to its value; the track clips the overshoot. |
| **Roll**   | The reading rolls to the new number.                         |
| **Fade**   | The bar changes colour as it crosses a threshold.            |

Timing and springiness follow the [motion style](/docs/motion-styles) you set, so this component moves like the rest of your app.

## Swap the import [#swap-the-import]

Already using UI SDK's meter with your own styles? Keep your markup and change one line. The primitive adds motion and nothing else.

```tsx
// Before
import { … } from "@ui-sdk/react/meter"

// After: same parts, same props, now animated
import { … } from "@/components/keyframery/primitives/meter"
```

## Parts [#parts]

The finished component exports 5 parts:

`Meter`, `MeterIndicator`, `MeterLabel`, `MeterTrack`, `MeterValue`

## Accessibility [#accessibility]

Keyboard, focus and screen-reader behaviour come from UI SDK and are not changed. With reduced motion turned on, nothing in the meter moves: changes happen at once or with a short fade. More in [Accessibility](/docs/accessibility).

## Source [#source]

The code that lands in your project. It is yours to change.

**components/keyframery/meter.tsx**

```tsx
"use client"

/* Styled meter: the animated primitive plus the Keyframery look. */

import {
  Meter as MeterRoot,
  MeterIndicator as MeterIndicatorPart,
  MeterLabel as MeterLabelPart,
  MeterTrack as MeterTrackPart,
  MeterValue as MeterValuePart,
} from "@/components/keyframery/primitives/meter"
import * as React from "react"

import { cn } from "@/lib/utils"

/* Label and value share the first row; the track spans the row below.
   `high` works like the native meter's: a reading above it is the bad range,
   and only then does the meter use the destructive colour. */
function Meter({
  className,
  high,
  ...props
}: React.ComponentProps<typeof MeterRoot> & { high?: number }) {
  const over = high !== undefined && props.value > high
  return (
    <MeterRoot
      data-high={over ? "" : undefined}
      className={cn(
        "group/meter grid w-full grid-cols-[minmax(0,1fr)_auto] items-baseline gap-x-3 gap-y-2",
        className,
      )}
      {...props}
    />
  )
}

function MeterLabel({ className, ...props }: React.ComponentProps<typeof MeterLabelPart>) {
  return (
    <MeterLabelPart
      className={cn("truncate text-[13px] leading-5 font-medium text-foreground", className)}
      {...props}
    />
  )
}

function MeterValue({ className, ...props }: React.ComponentProps<typeof MeterValuePart>) {
  return (
    <MeterValuePart
      className={cn(
        "col-start-2 text-[13px] leading-5 text-muted-foreground tabular-nums",
        "transition-colors duration-[calc(150ms*var(--kf-speed,1))] group-data-high/meter:text-destructive motion-reduce:transition-none!",
        className,
      )}
      {...props}
    />
  )
}

/* The track is a thin pill well. */
function MeterTrack({ className, ...props }: React.ComponentProps<typeof MeterTrackPart>) {
  return (
    <MeterTrackPart
      className={cn(
        "relative col-span-full h-1.5 w-full rounded-full bg-muted",
        "shadow-[inset_0_1px_2px_rgb(0_0_0/0.07),inset_0_0_0_1px_rgb(0_0_0/0.035)]",
        "dark:shadow-[inset_0_1px_2px_rgb(0_0_0/0.5),inset_0_0_0_1px_rgb(255_255_255/0.04)]",
        className,
      )}
      {...props}
    />
  )
}

/* The fill springs to each new reading (from the primitive) and turns destructive only above `high`. */
function MeterIndicator({ className, ...props }: React.ComponentProps<typeof MeterIndicatorPart>) {
  return (
    <MeterIndicatorPart
      className={cn(
        "rounded-full bg-primary",
        "shadow-[inset_0_1px_0_rgb(255_255_255/0.14)]",
        "group-data-high/meter:bg-destructive",
        className,
      )}
      {...props}
    />
  )
}

export { Meter, MeterIndicator, MeterLabel, MeterTrack, MeterValue }
```

**components/keyframery/primitives/meter.tsx**

```tsx
"use client"

/* Animated drop-in for `@ui-sdk/react/meter`: same parts, same props. Swap the import and keep your code.
   This file adds motion only. Colours, radii, shadows and spacing stay yours. */

import {
  MeterIndicator as MeterIndicatorPart,
  MeterTrack as MeterTrackPart,
  MeterValue as MeterValuePart,
} from "@ui-sdk/react/meter"
import * as React from "react"

import { cn } from "@/lib/utils"

export * from "@ui-sdk/react/meter"

/* Roll: every digit is a column of 0 to 9 that slides to its value on a spring; other characters
   (the decimal point, units) stay put. Positions are keyed from the right, so a new leading
   digit is added instead of everything shifting. Exported for other numbers. */
function Roll({ text, className }: { text: string; className?: string }) {
  const chars = text.split("")
  /* Screen readers get the plain value; the digit columns are only for the eye. */
  return (
    <>
    <span className="sr-only">{text}</span>
    <span data-slot="roll" aria-hidden className={cn("inline-flex h-[1lh] overflow-hidden whitespace-pre tabular-nums", className)}>
      {chars.map((c, i) => {
        const key = chars.length - i
        return /\d/.test(c) ? (
          <span
            key={key}
            style={{ "--d": Number(c) } as React.CSSProperties}
            className="flex flex-col transition-[translate] duration-[calc(500ms*var(--kf-speed,1))] ease-spring [translate:0_calc(var(--d)*-1lh)] motion-reduce:transition-none!"
          >
            {Array.from({ length: 10 }, (_, d) => (
              <span key={d} className="h-[1lh]">
                {d}
              </span>
            ))}
          </span>
        ) : (
          <span key={key}>{c}</span>
        )
      })}
    </span>
    </>
  )
}

/* The value rolls to each new reading. Pass children to render your own. */
function MeterValue({ children, ...props }: React.ComponentProps<typeof MeterValuePart>) {
  return <MeterValuePart {...props}>{children ?? ((state) => <Roll text={state.text} />)}</MeterValuePart>
}

/* The track clips the fill, so its spring overshoot never shows outside. */
function MeterTrack({ className, ...props }: React.ComponentProps<typeof MeterTrackPart>) {
  return <MeterTrackPart className={cn("overflow-hidden", className)} {...props} />
}

/* The fill moves to each new reading on a spring: it overshoots a little and settles. */
function MeterIndicator({ className, ...props }: React.ComponentProps<typeof MeterIndicatorPart>) {
  return (
    <MeterIndicatorPart
      className={cn(
        "block h-full [transition:width_calc(700ms*var(--kf-speed,1))_var(--ease-spring),background-color_calc(300ms*var(--kf-speed,1))_var(--ease-house)] motion-reduce:transition-none!",
        className,
      )}
      {...props}
    />
  )
}

export { MeterIndicator, MeterTrack, MeterValue, Roll }
```

## Questions

### How does the animated Meter for UI SDK move?

Spring: The bar springs to its value; the track clips the overshoot. Roll: The reading rolls to the new number. Fade: The bar changes colour as it crosses a threshold.

### Do I need Motion or Framer Motion for the animated Meter?

No. Every move is plain CSS, so there is nothing to install besides the component and UI SDK.

### Can I keep my own styling and only take the motion?

Yes. Import from `@/components/keyframery/primitives/meter` instead. It has the same parts and props as `@ui-sdk/react/meter` and adds motion only.

### What happens to the Meter when someone turns on reduced motion?

Nothing moves. State changes happen at once, or with a short fade.
