Meter

Meter displays a scalar quantity within a known range, such as remaining storage, battery charge, or a health level. It is a stateless controlled view: your Model owns the value, and Meter provides the ARIA and styling attributes. Use Progress instead when the value represents completion of a task.

Pass the current value and render the provided attribute groups. Spread attributes.label onto the visible label, attributes.meter onto the element that carries the meter role, and attributes.fill onto the filled portion. The fill width reflects the value's position within the range.

import type { HtmlBuilder } from 'foldkit/html'

import { Meter } from '@foldkit/ui'

const view = (h: HtmlBuilder<Message>) =>
  Meter.view(
    {
      id: 'health',
      value: 75,
      max: 100,
      valueText: '75 of 100 health',
      toView: attributes =>
        h.div(
          [h.Class('flex flex-col gap-2')],
          [
            h.span([...attributes.label], ['Health']),
            h.div(
              [
                ...attributes.meter,
                h.Class('h-3 w-full rounded-full bg-gray-200'),
              ],
              [
                h.div([
                  ...attributes.fill,
                  h.Class('h-full rounded-full bg-emerald-600'),
                ]),
              ],
            ),
          ],
        ),
    },
    h,
  )

low, high, and optimum expose application-specific thresholds as data-low, data-high, and data-optimum. They do not change the Meter's ARIA attributes; use them to style the ranges your application considers low, high, or optimal.

Meter is headless. Your toView callback controls its markup and styling.

The fill attribute group carries an inline width matching the value's position within the normalized range. Meter intentionally has no loading or complete state because it describes a measurement, not task progress.

The meter element receives role="meter", aria-valuemin, aria-valuemax, and aria-valuenow. By default, it is named through aria-labelledby, which points to the id carried by the label attribute group. Use ariaLabel when there is no visible label, or ariaLabelledBy to reference a different labeling element. When both overrides are provided, ariaLabel takes precedence.

Use valueText when the number needs a natural-language equivalent. It accepts either a string or a (value, max) => string formatter and sets aria-valuetext from the clamped value.

Meter clamps value into [min, max]. If max is lower than min, it is normalized to min before any ARIA or data attributes are emitted, so the rendered range remains valid.

Meter is read-only and has no keyboard interaction.

Configuration object passed to Meter.view().

Attribute groups provided to the toView callback.