HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
MeterView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA measurement in a known range, with optional bands that mark it good, fair, or poor.StableSince 0.1.0FeedbackUsageimport'@fusion.dev/helix/meter'import'@fusion.dev/helix-headless/meter'Preview
API ReferenceRoothelix-meterA measurement in a known range, with optional bands that mark it good, fair, or poor.
PropTypeDescriptionband"fair"|"good"|"poor"Sets the band directly, for a rule that low, high, and optimum cannot
express.bandLabelsPartial<Record<MeterBand, string>>Default{ fair: "Fair", good: "Good", poor: "Poor" }The words each band is said with under live, by its name, written as
JSON in the attribute: band-labels='{"poor":"Almost full"}'.emphasis"subtle"How strongly the reading is drawn. subtle draws it as a wash of its color.formatOptionsIntl.NumberFormatOptionsIntl.NumberFormat options the reading is written with, as React Aria's
Meter and ProgressBar take them: a unit, a currency, or a number of
decimals. Written as JSON in the attribute.highnumberBottom of the high band.labelstringDefault"Meter"Accessible name for the reading.livebooleanDefaultfalseSays the reading in a polite live region each time it moves into
another band, with the band's word, such as "92%, Poor".liveLabelstringDefault"{reading}, {band}"What live says as the reading moves into another band. {reading} is
the reading as it is shown, and {band} the band's words from
band-labels.localestringDefault""The locale the words and the percentage are in, such as fr for 72 %.lownumberTop of the low band.maxnumberDefault100Top of the range.minnumberDefault0Bottom of the range.optimumnumberThe point in the range where the reading is best.shape"arc"|"ring"Whether the reading is drawn as a bar, a ring, or an arc.showValuebooleanDefaultfalseWhether the reading is shown beside the bar.valuenumberDefault0Where the reading sits between min and max.valueTextstringDefault""Text that screen readers announce and the meter shows for the reading, in
place of the percentage.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptionlabelA visible label, above a bar and under a ring or an arc. Its words name it in place of label.
EventTypeDescriptionhelix-bandHelixBandEventFired when the reading moves into another band, with the band it is in now, or '' where it is in none. Not sent on the first render, since a meter that arrives in a band has not moved.
PartDescriptiongrooveThe unfilled circle, in ring and arc.indicatorThe part of the track the value fills.indicator-fairThe fill while the reading is in a band next to the good band. Set alongside indicator.indicator-goodThe fill while the reading is in the good band. Set alongside indicator.indicator-overThe fill while the value is above max. Set alongside indicator.indicator-poorThe fill while the reading is two bands from the good band. Set alongside indicator.indicator-underThe fill while the value is below min. Set alongside indicator.liveA polite region that says the reading as it moves into another band, under live, rendered from the first time it does. Hide it visually.tickA mark at low or at high.trackThe whole range.valueThe reading as text, shown when show-value is set.
CSS PropertyDescription--meter-alongWhere a bound sits on the arc, as a length along it.--meter-atWhere a bound sits on a linear track, as a percentage.--meter-colorThe fill color. Overrides the band's tone.--meter-fractionThe value as a fraction of the range, 0 to 1.--meter-label-colorThe color of a slotted label.--meter-label-gapThe space between a slotted label and the meter.--meter-label-sizeThe type size of a slotted label.--meter-ring-sizeThe width and height of the drawing in ring and arc.--meter-ring-widthThe thickness of the stroke in ring and arc.--meter-sizeThe thickness of the bar.--meter-sweepHow much of the circle the arc covers, as a path length.--meter-tick-colorThe color of the mark at each threshold.--meter-track-colorThe color of the groove behind the fill.--meter-transition-durationHow long the fill takes to move to a new reading, and to change its color. 0s moves it at once.--meter-value-colorThe color of the reading shown under show-value.--meter-value-gapThe space between the bar and the reading under show-value.--meter-value-sizeThe type size of the reading shown under show-value.
Custom stateDescriptionfairThe reading is in a band next to the good band.goodThe reading is in the good band.overThe value is above max.poorThe reading is two bands from the good band.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.underThe value is below min.
Roothelix-headless-meterA measurement in a known range, with optional bands that mark it good, fair, or poor.
PropTypeDescriptionband"fair"|"good"|"poor"Sets the band directly, for a rule that low, high, and optimum cannot
express.bandLabelsPartial<Record<MeterBand, string>>Default{ fair: "Fair", good: "Good", poor: "Poor" }The words each band is said with under live, by its name, written as
JSON in the attribute: band-labels='{"poor":"Almost full"}'.formatOptionsIntl.NumberFormatOptionsIntl.NumberFormat options the reading is written with, as React Aria's
Meter and ProgressBar take them: a unit, a currency, or a number of
decimals. Written as JSON in the attribute.highnumberBottom of the high band.labelstringDefault"Meter"Accessible name for the reading.livebooleanDefaultfalseSays the reading in a polite live region each time it moves into
another band, with the band's word, such as "92%, Poor".liveLabelstringDefault"{reading}, {band}"What live says as the reading moves into another band. {reading} is
the reading as it is shown, and {band} the band's words from
band-labels.localestringDefault""The locale the words and the percentage are in, such as fr for 72 %.lownumberTop of the low band.maxnumberDefault100Top of the range.minnumberDefault0Bottom of the range.optimumnumberThe point in the range where the reading is best.shape"arc"|"ring"Whether the reading is drawn as a bar, a ring, or an arc.showValuebooleanDefaultfalseWhether the reading is shown beside the bar.valuenumberDefault0Where the reading sits between min and max.valueTextstringDefault""Text that screen readers announce and the meter shows for the reading, in
place of the percentage.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptionlabelA visible label. Its words name the meter in place of label.
EventTypeDescriptionhelix-bandHelixBandEventFired when the reading moves into another band, with the band it is in now, or '' where it is in none. Not sent on the first render, since a meter that arrives in a band has not moved.
PartDescriptiongrooveThe unfilled circle, in ring and arc.indicatorThe part of the track the value fills.indicator-fairThe fill while the reading is in a band next to the good band. Set alongside indicator.indicator-goodThe fill while the reading is in the good band. Set alongside indicator.indicator-overThe fill while the value is above max. Set alongside indicator.indicator-poorThe fill while the reading is two bands from the good band. Set alongside indicator.indicator-underThe fill while the value is below min. Set alongside indicator.liveA polite region that says the reading as it moves into another band, under live, rendered from the first time it does. Hide it visually.tickA mark at low or at high.trackThe whole range, or the drawing in ring and arc.valueThe reading as text, shown when show-value is set.
CSS PropertyDescription--meter-alongWhere a bound sits on the arc, as a length along it.--meter-atWhere a bound sits on a linear track, as a percentage.--meter-fractionThe value as a fraction of the range, 0 to 1.--meter-sweepHow much of the circle the arc covers, as a path length.
Custom stateDescriptionfairThe reading is in a band next to the good band.goodThe reading is in the good band.overThe value is above max.poorThe reading is two bands from the good band.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.underThe value is below min.
Examples
NameDescriptionBandA temperature in its good band, one above it, and the same high reading set to poor with band.EmphasisOne meter at full strength and two with subtle emphasis, for readings that give context.Format OptionsA reading written in a unit with format-options, which takes Intl.NumberFormat options.LabelA visible label above the bar and under the ring, whose words also name the meter.Low High OptimumThree readings against the same low, high, and optimum, which set each one's color.Offset RangeA range from 15 to 30, for a reading that never goes near zero.Over MaxA value at the maximum and a value past it. The bar stops at its end.PreviewA measurement in a known range, with its value shown.PreviewA measurement in a known range, with its value shown.ShapesMeters drawn as an arc and as a ring.Value TextA reading shown as words you write with value-text.