Meter

A graphical display of a numeric value within a known range.

Storage

Usage

import { Meter, MeterLabel, MeterValue, MeterProgress } from '@appica/ui-react/meter'

<Meter value={64}>
  <MeterLabel>Storage</MeterLabel>
  <MeterValue />
  <MeterProgress />
</Meter>

A Meter displays a static measurement inside a known range — disk usage, a score, remaining battery — as opposed to Progress, which tracks a task moving toward completion. Compose it from parts: MeterLabel names the reading, MeterValue prints the formatted number, and MeterProgress draws the track and fill. The root lays them out on a grid — label top-left, value top-right, track spanning underneath — so you can drop in only the parts you need.

By default the fill uses the primary accent. Pass the low, high, and optimum thresholds and the indicator recolors itself to signal whether the current reading is good, borderline, or bad — green, amber, or red.

Examples

Default

A label, a formatted value, and a track. value is read against the default 0–100 range, and MeterValue renders it as a percentage out of the box.

Storage

import { Meter, MeterLabel, MeterValue, MeterProgress } from '@appica/ui-react/meter'

export default function MeterDefault() {
  return (
    <Meter value={64} className="w-72 max-w-full">
      <MeterLabel>Storage</MeterLabel>
      <MeterValue />
      <MeterProgress />
    </Meter>
  )
}

Status thresholds

Pass low, high, and optimum and the indicator colors itself by zone: optimum (green) when the value sits on the same side as optimum, suboptimum (orange) one zone away, and invalid (red) at the far end. Here optimum={10} marks low usage as healthy, so a high reading turns red.

Operations

Marketing

Infrastructure

import { Meter, MeterLabel, MeterValue, MeterProgress } from '@appica/ui-react/meter'

const USAGE = [
  { label: 'Operations', value: 32 },
  { label: 'Marketing', value: 64 },
  { label: 'Infrastructure', value: 94 },
]

export default function MeterStatus() {
  return (
    <div className="flex w-72 max-w-full flex-col gap-5">
      {USAGE.map((item) => (
        <Meter key={item.label} value={item.value} low={40} high={75} optimum={10}>
          <MeterLabel>{item.label}</MeterLabel>
          <MeterValue />
          <MeterProgress />
        </Meter>
      ))}
    </div>
  )
}

Formatting the value

The root's format takes Intl.NumberFormatOptions — render the value as currency, a unit, and so on. For full control, pass a function as MeterValue's children to wrap the formatted string in your own text.

Monthly budget

Backup size

'use client'

import { Meter, MeterLabel, MeterValue, MeterProgress } from '@appica/ui-react/meter'

export default function MeterFormatting() {
  return (
    <div className="flex w-72 max-w-full flex-col gap-6">
      <Meter value={1280} max={2000} format={{ style: 'currency', currency: 'USD' }} low={1000} high={1800} optimum={0}>
        <MeterLabel>Monthly budget</MeterLabel>
        <MeterValue />
        <MeterProgress />
      </Meter>

      <Meter value={3.4} max={8} format={{ style: 'unit', unit: 'gigabyte', maximumFractionDigits: 1 }}>
        <MeterLabel>Backup size</MeterLabel>
        <MeterValue>{(formatted) => `${formatted} of 8 GB`}</MeterValue>
        <MeterProgress />
      </Meter>
    </div>
  )
}

Password strength (controlled)

A real-world meter: score the input as the user types, map the score to a custom range (max={4}), and use the thresholds to drive the red → amber → green color. The MeterValue children print a word ("Fair", "Strong") instead of a number.

'use client'

import * as React from 'react'
import { Meter, MeterValue, MeterProgress } from '@appica/ui-react/meter'
import { Input } from '@appica/ui-react/input'
import { Lock } from '@appica/icons-react'

const LEVELS = ['Too weak', 'Weak', 'Fair', 'Good', 'Strong'] as const

function scorePassword(value: string) {
  if (value.length < 3) return 0
  let score = 1
  if (value.length >= 10) score++
  if (/[A-Z]/.test(value) && /[a-z]/.test(value)) score++
  if (/[0-9]/.test(value) || /[^A-Za-z0-9]/.test(value)) score++
  return score
}

export default function MeterStrength() {
  const [password, setPassword] = React.useState('')
  const score = scorePassword(password)

  return (
    <div className="flex w-72 max-w-full flex-col gap-2">
      <Input
        startSlot={<Lock />}
        type="password"
        autoComplete="new-password"
        value={password}
        onChange={(event) => setPassword(event.target.value)}
        placeholder="Choose a password"
        aria-label="Password"
      />
      <Meter
        value={score}
        max={4}
        low={2}
        high={2}
        optimum={4}
        aria-label="Password strength"
        statusClassNames={{
          invalid: 'bg-error-emphasis',
          suboptimum: 'bg-warning-emphasis',
          optimum: 'bg-success-emphasis',
        }}
      >
        <MeterValue className="text-foreground-muted text-xs">{() => LEVELS[score]}</MeterValue>
        <MeterProgress />
      </Meter>
    </div>
  )
}

Minimal

Drop MeterValue (and even MeterLabel) to render a bare track — handy for compact lists where the label alone carries the meaning. Restyle the track height and label with className.

TypeScript

React

CSS

Rust

import { Meter, MeterLabel, MeterProgress } from '@appica/ui-react/meter'

const SKILLS = [
  { label: 'TypeScript', value: 90 },
  { label: 'React', value: 82 },
  { label: 'CSS', value: 70 },
  { label: 'Rust', value: 38 },
]

export default function MeterMinimal() {
  return (
    <div className="flex w-64 max-w-full flex-col gap-3">
      {SKILLS.map((skill) => (
        <Meter key={skill.label} value={skill.value} className="gap-1">
          <MeterLabel className="text-foreground text-xs font-normal">{skill.label}</MeterLabel>
          <MeterProgress className="h-1" />
        </Meter>
      ))}
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

Under RTL the label and value swap sides and the track fills from the right. For setup details and caveats, see the RTL guide.

التخزين

النطاق الترددي

API reference

Meter wraps Base UI's Meter. Each part forwards ref and its remaining native attributes to the matching Base UI primitive — the tables below list the Appica additions and the most common props. When any threshold is set, the root exposes data-status (optimum | suboptimum | invalid) for styling, and the indicator carries data-slot="meter-indicator" with the threshold-derived background class.

Meter

The root. Owns the value, the range, and the threshold logic, and provides the resolved indicator color to MeterProgress. Renders a <div role="meter">.

Prop	Type	Default	Description
`value`	`number`	—	Required. The current value.
`min`	`number`	`0`	Lower bound of the range.
`max`	`number`	`100`	Upper bound of the range.
`low`	`number`	—	Upper edge of the "low" zone. Enables status coloring.
`high`	`number`	—	Lower edge of the "high" zone. Enables status coloring.
`optimum`	`number`	—	The ideal value; the zone it lands in becomes the green "optimum" zone. Enables status coloring.
`statusClassNames`	`{ optimum?, suboptimum?, invalid?, default? }`	—	Override the indicator background class per status (and the no-threshold `default`).
`format`	`Intl.NumberFormatOptions`	—	Formatting passed to `Intl.NumberFormat` for the displayed value.
`locale`	`Intl.LocalesArgument`	—	Locale used by `Intl.NumberFormat`.
`getAriaValueText`	`(formatted: string, value: number) => string`	—	Build the human-readable `aria-valuetext`.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace the rendered element, or compose it with another component.
`className`	`string \| ((state) => string)`	—	Extra classes, merged via `tailwind-merge`. Override the default grid layout here.
`style`	`CSSProperties \| ((state) => CSSProperties)`	—	Inline styles, optionally derived from state.

MeterLabel

Names the meter and is wired to the root via aria-labelledby. Renders a <span>.

Prop	Type	Default	Description
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace or compose the rendered element.
`className`	`string \| ((state) => string)`	—	Extra classes, merged via `tailwind-merge`.
`style`	`CSSProperties \| ((state) => CSSProperties)`	—	Inline styles, optionally derived from state.

MeterValue

Prints the formatted value. Renders a <span>.

Prop	Type	Default	Description
`children`	`((formatted: string, value: number) => ReactNode) \| null`	—	Render function to fully customize the displayed text. Omit for the default.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace or compose the rendered element.
`className`	`string \| ((state) => string)`	—	Extra classes, merged via `tailwind-merge`.
`style`	`CSSProperties \| ((state) => CSSProperties)`	—	Inline styles, optionally derived from state.

MeterProgress

The track and fill. Wraps the Track and renders the Indicator inside it, reading the resolved color from the root. Renders a <div>.

Prop	Type	Default	Description
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace or compose the track element.
`className`	`string \| ((state) => string)`	—	Extra classes on the track, merged via `tailwind-merge`.
`style`	`CSSProperties \| ((state) => CSSProperties)`	—	Inline styles, optionally derived from state.

Accessibility

Meter renders role="meter" with aria-valuenow, aria-valuemin, and aria-valuemax set from value, min, and max.
Give every meter an accessible name — either a MeterLabel (wired automatically via aria-labelledby) or an aria-label on the root when you omit the visible label.
format and getAriaValueText shape aria-valuetext, so screen readers announce "$1,280.00" rather than a bare number.
Color alone shouldn't carry meaning — pair the status colors with the value or a word (as in the password-strength example) so the state is clear without color.
The fill transition honours prefers-reduced-motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Meter

Usage

Examples

Default

Status thresholds

Formatting the value

Password strength (controlled)

Minimal

RTL

API reference

Meter

MeterLabel

MeterValue

MeterProgress

Accessibility