StackedMeterNew

A stacked meter splits a single track into proportional colored segments to show how a whole breaks down into parts, such as the languages of a repository or the categories filling a storage quota.

Import

import { StackedMeter } from 'heroui-native-pro';

Anatomy

<StackedMeter segments={segments}>
  <StackedMeter.Label>...</StackedMeter.Label>
  <StackedMeter.Track>{() => <StackedMeter.Segment />}</StackedMeter.Track>
  <StackedMeter.Legend>
    {() => (
      <StackedMeter.LegendItem>
        <StackedMeter.LegendIndicator />
        <StackedMeter.LegendLabel />
        <StackedMeter.LegendValue />
      </StackedMeter.LegendItem>
    )}
  </StackedMeter.Legend>
</StackedMeter>

• StackedMeter: Root container that owns the segments data. Computes each segment's share of the total (the sum of the values, or a larger maxValue) and its formatted value text. With no children it renders the track and the legend; plain string children render a label, the track, and the legend.
• StackedMeter.Label: Title text describing the meter.
• StackedMeter.Track: Rounded horizontal container rendering one segment per non-zero segment, followed by the empty remainder when maxValue exceeds the sum. Accepts a render function called once per segment. Exposed to screen readers as a single element summarizing every segment.
• StackedMeter.TrackBackground: Optional theme-aware background container rendered behind the empty remainder of the track. Mounted automatically when the active theme registers default background content (e.g. glass). Replace or remove it via the Track's background prop.
• StackedMeter.Segment: Animated element sized by the segment's share of the track. Reads its segment from context.
• StackedMeter.Legend: Wrapping row rendering one legend item per segment. Accepts a render function called once per segment.
• StackedMeter.LegendItem: Row describing one segment. Defaults to indicator, label, and value. Exposed to screen readers as a single element.
• StackedMeter.LegendIndicator: Dot painted with the segment's color.
• StackedMeter.LegendLabel: Segment name text.
• StackedMeter.LegendValue: Formatted segment value, rendered with tabular figures.

Usage

Basic usage

Pass the segments and compose the parts. Segments without a color are assigned chart-1 through chart-5 in order.

const LANGUAGES = [
  { id: 'ts', label: 'TypeScript', value: 96.3 },
  { id: 'css', label: 'CSS', value: 2.6 },
  { id: 'js', label: 'JavaScript', value: 1.1 },
];

<StackedMeter segments={LANGUAGES}>
  <StackedMeter.Label>Languages</StackedMeter.Label>
  <StackedMeter.Track />
  <StackedMeter.Legend />
</StackedMeter>;

String children shortcut

Pass a string as children to auto-render the label, track, and legend.

<StackedMeter segments={LANGUAGES}>Languages</StackedMeter>

Sizes

Switch the track height with the size prop.

<StackedMeter segments={segments} size="sm" />
<StackedMeter segments={segments} size="md" />
<StackedMeter segments={segments} size="lg" />

Colors

Set color on a segment to use a color variant. Use colorClassName for colors outside the variant set; it applies to both the segment and its legend indicator.

<StackedMeter
  segments={[
    { id: 'done', label: 'Done', value: 12, color: 'success' },
    { id: 'review', label: 'In review', value: 5, color: 'warning' },
    { id: 'blocked', label: 'Blocked', value: 2, color: 'danger' },
    { id: 'swift', label: 'Swift', value: 4, colorClassName: 'bg-[#f05138]' },
  ]}
/>

Capacity

Set maxValue to measure the segments against a fixed capacity. The unused part of the track stays empty. Combine it with formatOptions to show raw values instead of percentages.

<StackedMeter
  segments={STORAGE}
  maxValue={128}
  formatOptions={{ style: 'unit', unit: 'gigabyte', maximumFractionDigits: 1 }}
>
  Storage
</StackedMeter>

Custom legend

Pass a render function to StackedMeter.Legend (or StackedMeter.Track). It is called once per segment, and the parts it returns read that segment from context.

<StackedMeter segments={segments}>
  <StackedMeter.Track />
  <StackedMeter.Legend className="flex-col items-stretch gap-y-3">
    {(segment) => (
      <StackedMeter.LegendItem className="justify-between">
        <View className="flex-row items-center gap-2">
          <StackedMeter.LegendIndicator />
          <StackedMeter.LegendLabel />
        </View>
        <StackedMeter.LegendValue>
          {segment.value} files
        </StackedMeter.LegendValue>
      </StackedMeter.LegendItem>
    )}
  </StackedMeter.Legend>
</StackedMeter>

Track only

Render only the track and provide accessibilityLabel on the root. It prefixes the summary screen readers announce for the track.

<StackedMeter segments={segments} accessibilityLabel="Languages">
  <StackedMeter.Track />
</StackedMeter>

Disabled

Set isDisabled to lower the opacity and mark the component as disabled for accessibility.

<StackedMeter segments={segments} isDisabled />

Render function children

Use a render function on the root to access the computed segment states.

<StackedMeter segments={segments}>
  {({ segments, total, summaryText }) => (
    <>
      <StackedMeter.Track />
      <AppText>{summaryText}</AppText>
    </>
  )}
</StackedMeter>

Example

import { StackedMeter } from 'heroui-native-pro';
import { View } from 'react-native';

const LANGUAGES = [
  {
    id: 'ts',
    label: 'TypeScript',
    value: 96.3,
    colorClassName: 'bg-[#3178c6]',
  },
  { id: 'css', label: 'CSS', value: 2.6, colorClassName: 'bg-[#663399]' },
  { id: 'js', label: 'JavaScript', value: 1.1, colorClassName: 'bg-[#f1e05a]' },
];

export default function StackedMeterExample() {
  return (
    <View className="flex-1 px-5 items-center justify-center">
      <View className="w-80">
        <StackedMeter segments={LANGUAGES}>
          <StackedMeter.Label>Languages</StackedMeter.Label>
          <StackedMeter.Track />
          <StackedMeter.Legend />
        </StackedMeter>
      </View>
    </View>
  );
}

API Reference

StackedMeter

StackedMeterSegment

StackedMeterSegmentState

Extends StackedMeterSegment with computed fields.

StackedMeterSize

StackedMeterColor

StackedMeterRenderProps

StackedMeterRootAnimation

Animation configuration for the StackedMeter root. Can be:

• "disable-all": Disable all animations including children (cascades down)
• undefined: Use default animations

StackedMeter.Label

StackedMeter.Track

StackedMeter.TrackBackground

Absolute-fill container rendered behind the empty remainder of the track. With no children, the active library theme decides the default content (e.g. a glass blur layer); pass children to host custom content with the same positioning and clipping.

StackedMeter.Segment

Note: flexGrow is occupied by the animation and cannot be set via className. To fully control the segment size, set isAnimatedStyleActive={false}.

StackedMeterSegmentAnimation

Animation configuration for StackedMeter.Segment. Can be:

• false or "disabled": Disable the share transition
• true or undefined: Use default animations
• object: Custom animation configuration

StackedMeter.Legend

StackedMeter.LegendItem

StackedMeter.LegendIndicator

StackedMeter.LegendLabel

StackedMeter.LegendValue

Hooks

useStackedMeter

Hook to access the StackedMeter context. Must be used within a StackedMeter component.

import { useStackedMeter } from 'heroui-native-pro';

const { segments, total, remainderPercentage, summaryText, size, isDisabled } =
  useStackedMeter();

Returns: StackedMeterContextValue

useStackedMeterSegment

Hook to access the current segment inside a StackedMeter.Track or StackedMeter.Legend render function (or the default content).

import { useStackedMeterSegment } from 'heroui-native-pro';

const { segment } = useStackedMeterSegment();

Returns: StackedMeterSegmentContextValue