VolumeIndicator

Updated: Sep 24, 2026
VolumeIndicator is a horizontal pill — an icon on the left, a filled bar filling the rest — that reports the volume level your app currently believes is in effect. It exists for transient feedback while something else changes the volume, so show it as the value moves and take it away when the adjustment settles.
It is display-only. It never takes focus, handles no pointer or key input, and does not change the volume; the value is entirely yours to supply. That is the difference between this and a control: when the user is meant to adjust something, use SliderBar, IsolatedControl, or a ListItem with a slider. Its vertical sibling is ZoomIndicator.

Usage

import { VolumeIndicator } from '@wearables-ui-toolkit/mrbd';

const FILL_WIDTH = { width: '100%' } as const;

type Props = {
  volume: number;
  isAdjusting: boolean;
};

export function VolumeOverlay({ volume, isAdjusting }: Props) {
  if (!isAdjusting) {
    return null;
  }

  return (
    <div className="volume-overlay">
      <VolumeIndicator value={volume} animated style={FILL_WIDTH} />
    </div>
  );
}
.volume-overlay {
  position: absolute;
  left: var(--uit-spacing-large);
  right: var(--uit-spacing-large);
  bottom: var(--uit-spacing-large);
  display: flex;
  justify-content: center;
}
The pill sizes itself to its content by default, subject to a minimum bar width that keeps the level readable. Because style is merged over the component’s own container styles, setting a width there is the reliable way to stretch it across an overlay.
When the level comes from a stepped source, pass those steps directly instead of converting to a fraction, and swap the glyph to match the state:
import { VolumeIndicator } from '@wearables-ui-toolkit/mrbd';
import type { IconSource } from '@wearables-ui-toolkit/mrbd';

type Props = {
  step: number;
  stepCount: number;
  mutedIcon: IconSource;
};

export function CallVolume({ step, stepCount, mutedIcon }: Props) {
  return (
    <VolumeIndicator
      value={step}
      minimumValue={0}
      maximumValue={stepCount}
      icon={step === 0 ? mutedIcon : undefined}
      announceUpdatesForAccessibility
      aria-label="Call volume"
    />
  );
}

Props

The full prop type is VolumeIndicatorProps, which extends HTMLAttributes<HTMLDivElement>.
PropTypeDefaultDescription
value
number
—
Required. Current level. Clamped to the range before it is drawn and reported.
minimumValue
number
0
Low end of the range, reported as aria-valuemin.
maximumValue
number
1
High end of the range, reported as aria-valuemax.
icon
IconSource \| null
speaker glyph
Icon shown at the left. Pass null to drop the icon area; the gap beside the bar closes with it. undefined keeps the default glyph, so a conditional expression can fall back to it.
animated
boolean
false
Tween value changes instead of snapping. Applies to every change while set.
announceUpdatesForAccessibility
boolean
false
Publish the rounded percentage into a polite live region so screen readers narrate each change.
aria-label
string
'Volume'
Appended after the percentage in the accessible name. Blank or whitespace-only labels fall back to the default.
aria-labelledby
string
—
Id of external label text, applied to the progressbar element. It replaces the generated name outright, so the percentage is no longer part of it.
aria-describedby
string
—
Id of additional description text, applied to the progressbar element.
className
string
''
Added to the root element.
style
CSSProperties
{}
Merged onto the root element.
The ref is forwarded to the root element. Any aria-* attribute you pass is applied to the inner progressbar element, where it can take effect; every other DOM prop, including data-*, lands on the root. The component writes role, aria-valuenow, aria-valuemin, and aria-valuemax on that inner element last, so values you pass for those four are overwritten.

Behavior

  • Range and clamping. The value is clamped to [minimumValue, maximumValue], so an out-of-range reading never overdraws the bar. Keep the range matched to the source of truth — a step count, for example — rather than converting to a fraction yourself; the component derives the percentage it reports and announces. When the minimum and maximum are equal it reports 100%.
  • Layout. A horizontal pill: the icon area, then the bar filling the remaining width. The height is fixed and the bar has a minimum width, so the pill has an intrinsic minimum size; dropping the icon with icon={null} removes the icon area and the gap that separated it from the bar, while the pill’s horizontal padding stays the same.
  • Bar appearance. The bar always renders in its active, expanded appearance so the pill stays legible as a transient overlay on the additive-light display. There is no idle or dimmed variant.
  • Materials and color. The pill is filled with --uit-color-background-elevation2 and fully rounded; the icon is tinted with --uit-color-icon-primary, and the bar’s filled portion uses --uit-color-control-active.
  • Icon.icon takes any IconSource: an inline vector, a caller asset referenced by URL, or a plain URL string. The component owns the icon’s size and tint, so pass the source and nothing else.
  • Motion. With animated unset, value changes apply immediately, which is usually what you want for a value the user is actively changing. Setting it applies a sampled spring transition to the fill and keeps applying it to every later change while it stays set.
  • Reduced motion. The component does not read a motion preference for you. Call usePrefersReducedMotion and drop animated when the user has asked for less motion.
  • Not interactive. Nothing about the pill is interactive. It has no hover, press, or focus state and takes no part in directional navigation.

Accessibility

  • Renders an element with role="progressbar" carrying aria-valuenow (the clamped value, in your units), aria-valuemin, and aria-valuemax. The drawn bar inside it is hidden from assistive technology, so the component contributes exactly one progressbar to the accessibility tree.
  • The accessible name is the rounded percentage followed by a label, which defaults to Volume — 50%, Volume. Supply aria-label to replace that trailing label with something more specific, such as Call volume. A label that is empty or only whitespace falls back to the default.
  • Live-region announcements are off by default. Turning announceUpdatesForAccessibility on publishes just the percentage into a polite, atomic live region that sits outside the progressbar element so the change is reliably picked up. Enable it only when the overlay is the sole feedback for the change; a value that moves continuously can otherwise flood the live region.
  • The indicator contributes no tab stop, so it can never be reached by directional navigation and never steals focus from the content behind it.
  • Use aria-labelledby when the naming text already exists on screen, and aria-describedby for supplementary detail; both are forwarded to the progressbar element.
  • Drive the value from whatever actually owns the volume, and update it as that source changes.
  • Show the pill while the value moves and dismiss it shortly after it settles.
  • Give it a specific aria-label when a screen can show more than one level.
  • Swap the icon to reflect a muted or alternate output state rather than hiding the whole pill.

Avoid

  • Present it as feedback rather than something the user can drag or press.
  • Show it as a transient readout. Use a settings row for a persistent control.
  • Avoid rebuilding the pill with a bare SliderBar and your own background; this component already owns the material, icon slot, and semantics.
  • Pass the level in its source units and provide the real range. The component computes the percentage, so callers do not need to normalize the value.
  • Avoid rotating it to stand in for ZoomIndicator; that component already handles the vertical case.