[Feature] StackedMeter — segmented capacity indicator (sibling to Meter)

[aosmcleod]

Feature description

A StackedMeter component — a segmented horizontal bar that visualises a breakdown of a known capacity. Think storage usage by file type, team capacity by role, language breakdown in a repo, or budget allocation by category.

This is the multi-segment sibling of the existing Meter component. Where Meter shows a single value against a maximum, StackedMeter shows multiple named segments that sum toward a total.

Why this belongs in HeroUI

1. Common pattern: GitHub language bars, macOS storage breakdown, Jira sprint capacity, Figma plan usage — this pattern appears in nearly every dashboard and settings UI.
2. Not trivially composable: Getting the ARIA right (role="group" + per-segment role="meter"), the tooltip integration, the fill animation, and the colour coordination requires enough orchestration that a first-party component saves significant time.
3. Sibling to Meter: Shares the same size scale, visual proportions, and colour tokens. Belongs in the same component family.
4. Accessibility-first: Each segment is individually announced by screen readers with its label and value. The Legend is aria-hidden (decorative). The root is role="group" with an aria-label.

API design

Data-driven (segments as a prop, not compound children) so the Track, Output, and Legend slots can all read consistent data without a registration pattern:

import { StackedMeter } from '@heroui/react';

const segments = [
  { id: 'photos', value: 45, label: 'Photos', color: 'accent' },
  { id: 'videos', value: 20, label: 'Videos', color: 'success' },
  { id: 'docs',   value: 10, label: 'Documents', color: 'warning' },
  { id: 'other',  value: 5,  label: 'Other', color: 'default' },
];

<StackedMeter segments={segments} maxValue={128} aria-label="Storage usage">
  <StackedMeter.Output>
    {({ total, maxValue, format }) => `${format(total)} / ${format(maxValue)} GB`}
  </StackedMeter.Output>
  <StackedMeter.Track />
  <StackedMeter.Legend />
</StackedMeter>

Compound slots

Slot	Purpose
StackedMeter.Output	Formatted total / max display. Render prop for custom formatting.
StackedMeter.Track	The horizontal bar with coloured segments. Each segment gets a Tooltip.
StackedMeter.Legend	Colour swatches + labels below the bar. aria-hidden.

Props

Prop	Type	Default	Description
segments	StackedMeterSegment[]	required	Segments to render (id, value, label, color, tooltip?)
maxValue	number	100	Total capacity (denominator)
formatOptions	Intl.NumberFormatOptions	—	Number formatting for Output and tooltips
size	'sm' | 'md' | 'lg'	'md'	Track thickness (matches Meter's size scale)
animate	boolean	true	Fill-in animation on mount (respects prefers-reduced-motion)

Segment type

interface StackedMeterSegment {
  id: string;
  value: number;
  label: string;
  color?: 'default' | 'accent' | 'success' | 'warning' | 'danger';
  tooltip?: ReactNode;
}

Visual reference

I have working screenshots from a production implementation of this component. The design matches HeroUI's existing Meter proportions and colour tokens:

Implementation notes

• Built on React context (compound pattern matching HeroUI's conventions)
• Each segment wraps in HeroUI's Tooltip for hover details
• Fill animation uses CSS transition: width with a staggered delay per segment index
• prefers-reduced-motion: reduce skips the animation
• Overflow handling: if segment values exceed maxValue, segments are clamped proportionally (with a dev-mode console warning)
• Colour tokens: uses HeroUI's existing --accent, --success, --warning, --danger, --default (and could use --info, --note if [Feature] Extend semantic status colours with --info, --note, and --draft #6563 lands)

Prior art

• GitHub language bars (repo overview)
• macOS System Settings → Storage
• Linear project progress bars
• Stripe billing usage meters