Kappa / Meter

<script setup>
import { Meter } from "@dicehub/kappa/components/meter";
</script>

<template>
  <Meter label="Storage used" :value="65" />
</template>

Installation

Meter is part of the main Kappa package. It uses Vue and native WAI-ARIA meter semantics. It adds no behavior dependency.

Barrel

import { Meter } from "@dicehub/kappa";

Granular

import { Meter } from "@dicehub/kappa/components/meter";

Usage

Use Meter for a measurement with a meaningful minimum and maximum, such as storage, battery charge, or capacity. Do not use it for task completion.

<script setup>
import { Meter } from "@dicehub/kappa/components/meter";
</script>

<template>
  <Meter label="Storage used" :value="65" />
</template>

Composition

Typical part hierarchy

Meter <div role="meter">
├── meter-header
│   ├── meter-label
│   └── meter-value (optional)
└── meter-track
    └── meter-indicator

The internal anatomy followsBase UI Meter. Ark UI has no Meter primitive. Kappa therefore owns this small WAI-ARIA composition and exposes stable data slots.

Examples

Custom Range and Value Text

Set the numeric range independently from the human-readable value text.

<script setup>
import { Meter } from "@dicehub/kappa/components/meter";
</script>

<template>
  <Meter
    label="API request quota"
    :value="750"
    :max="1000"
    value-text="750 / 1,000 requests"
  />
</template>

Sizes

Use the small, default, and large densities to match the surrounding information.

<script setup>
import { Meter, type MeterSize } from "@dicehub/kappa/components/meter";

const sizes = [
  { label: "Small meter", size: "sm", value: 24 },
  { label: "Default meter", size: "base", value: 56 },
  { label: "Large meter", size: "lg", value: 82 },
] satisfies Array<{ label: string; size: MeterSize; value: number }>;
</script>

<template>
  <Meter
    v-for="item in sizes"
    :key="item.size"
    :label="item.label"
    :size="item.size"
    :value="item.value"
  />
</template>

Semantic Tones

Select a tone from the meaning of the measurement. Meter does not infer whether a high or low value is good.

<script setup>
import { Meter, type MeterTone } from "@dicehub/kappa/components/meter";

const readings = [
  { label: "Accent", tone: "accent", value: 62 },
  { label: "Neutral", tone: "neutral", value: 52 },
  { label: "Healthy capacity", tone: "success", value: 38 },
  { label: "Capacity warning", tone: "warning", value: 78 },
  { label: "Capacity critical", tone: "danger", value: 94 },
] satisfies Array<{ label: string; tone: MeterTone; value: number }>;
</script>

<template>
  <Meter
    v-for="reading in readings"
    :key="reading.tone"
    :label="reading.label"
    :tone="reading.tone"
    :value="reading.value"
  />
</template>

Hidden Visual Value

Hide repeated visual text without removing the value from assistive technology.

The numeric value remains available to assistive technology.

<script setup>
import { Meter } from "@dicehub/kappa/components/meter";
</script>

<template>
  <Meter label="Battery charge" :value="48" :show-value="false" />
</template>

Accessibility

Meter always has a visible label and an accessible name.
Kappa clamps aria-valuenow between the resolved minimum and maximum.
Use valueText when a percentage does not explain the measurement.
showValue=false hides only the visual value. Assistive value text remains.
Do not use Meter for loading or task completion. Those states require a progress bar.
Color is supplementary. Keep the label and value text sufficient without color.

API Reference

Meter

Renders a labelled div with role=meter. Native attributes, data attributes, consumer classes, and CSS variables pass to the root.

Prop	Type	Default	Description
`label*`	`string`	`—`	Visible label and accessible name for the measurement.
`value*`	`number`	`—`	Current measurement. Values outside the range are clamped.
`min`	`number`	`0`	Lowest value in the known range.
`max`	`number`	`100`	Highest value in the known range. It must be greater than min.
`valueText`	`string`	`percentage`	Human-readable visible and assistive value text.
`showValue`	`boolean`	`true`	Shows the formatted value beside the label.
`size`	`"sm" \| "base" \| "lg"`	`"base"`	Controls text and track density.
`tone`	`"accent" \| "neutral" \| "success" \| "warning" \| "danger"`	`"accent"`	Applies a consumer-selected semantic indicator color.

Data Slots

Slot	Element	Description
`meter`	`div`	Labelled meter root.
`meter-header`	`div`	Label and visible value row.
`meter-label`	`span`	Visible accessible name.
`meter-value`	`span`	Optional visible value text.
`meter-track`	`div`	Visual representation of the complete range.
`meter-indicator`	`div`	Filled portion of the range.

Data Attributes

Attribute	Value	Description
`data-size`	`"sm" \| "base" \| "lg"`	Resolved density.
`data-tone`	`"accent" \| "neutral" \| "success" \| "warning" \| "danger"`	Resolved indicator tone.
`data-value-state`	`"empty" \| "partial" \| "full"`	Clamped position in the range.

Exports

Export	Description
`Meter`	Labelled scalar measurement component.
`MeterProps`	Public prop contract.
`MeterSize / MeterTone / MeterValueState`	Public visual and value-state types.
`METER_SIZES / METER_TONES`	Supported size and tone lists.
`METER_DEFAULT_*`	Public default values.
`clampMeterValue / getMeterPercentage / formatMeterValue`	Range and formatting helpers.
`resolveMeter*`	Safe range, value, label, size, and tone resolvers.