CompositionBar
A single horizontal bar split into proportional, color-coded segments — each category's share of the total, the composition read for open-ended counts with no fixed maximum.
Implementation previewEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Example source
packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.stories.tsxExport DefaultImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A single horizontal bar split into proportional, color-coded segments — each category's share of the total, the composition read for open-ended counts with no fixed maximum.
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { CompositionBar } from '@cloakedinc/design-system';CompositionBarCompositionBarProps
packages/design-system/src/components/visualizations/CompositionBar/CompositionBar.tsx:12
| Prop | Type | Presence | Notes |
|---|---|---|---|
items | readonly CategoryDatum[] | Required | Category segments rendered left to right in the given order. |
ariaLabel | string | undefined | Optional | Accessible label for meaningful chart content. |
testId | string | undefined | Optional | Optional test selector. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
A single horizontal bar split into proportional, color-coded segments — each category's share of the total.
When to use
Reach for it when the counts are open-ended — a running total with no fixed maximum or goal.
A share of the whole reads honestly at any scale: a brand-new user and a power user both see a
meaningful mix. CategoryBars scales length to the largest value, which pegs the leader near full
and implies a ceiling that does not exist, so prefer this when the question is "what's the mix?"
rather than "read the exact magnitudes."
Each segment takes its color; omit color and segments cycle the default category palette. Pair
it with a labeled legend when the reader also needs the exact counts.
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- bar
- Label
- Bar
- Description
- The full-width pill track that holds the segments.
- Required
- true
- Id
- segment
- Label
- Segment
- Description
- A colored slice whose width is one category's share of the total.
Allowed Design Choices
- Variants
- Base
- Label
- Base
- Description
- Category data changes the segment widths and colors without changing the bar treatment.
- Sizes
Variants
- Id
- base
- Label
- Base
- Description
- One pill bar of proportional category segments.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- bar-height
- Label
- Bar height
- Kind
- exact
- Token
- --cds-size-16
- Value
- 16
- Unit
- px
- Applies To
- bar
Layout
- Alignment
- Segments sit flush in a single row, each sized to its share of the total.
- Flow
- Segments render left to right in the order given.
- Notes
- The bar is a full-width pill (
--cds-radius-full) that clips its segments to rounded ends. - Segment widths are shares of the summed whole, not of the largest value.
- Zero-value categories are dropped so no invisible slivers accumulate.
- The bar is a full-width pill (
Typography And Color
- Typography
- None specified
- Colors
- Label
- Segment
- Description
- Each segment uses its own
item.color— canonically one of the PII category tokens (PII_CATEGORY_COLOR_VARS), one per category — or cycles the default category palette when none is given. - Token
- --cds-pii-category-name
States
- Id
- composition
- Label
- Composition
- Description
- Segments render in order, each sized to its share of the total.
- Id
- default-palette
- Label
- Default palette
- Description
- Segments without a color cycle the built-in category palette.
- Id
- empty
- Label
- Empty
- Description
- A zero total renders nothing, so pair with an upstream empty state.
Behavior
- Label
- Share of the whole
- Description
- Segment width is each value divided by the sum, so the bar always fills and never implies a fixed maximum.
- Label
- Palette fallback
- Description
- Segments take their own color, or cycle the default category palette when none is given.
- Label
- Drops empty slices
- Description
- Categories at or below zero are omitted rather than rendered as invisible segments.
Accessibility
- Label
- Meaningful chart
- Description
- Pass an accessible label so the bar is announced as a meaningful image.
- Label
- Pair with a legend
- Description
- The bar shows proportion only; surface category labels and exact counts in an adjacent legend.
Content Adaptation
- Label
- Open-ended counts
- Description
- Use CompositionBar when a running total has no goal or maximum and the reader needs the mix, not exact magnitudes.
- Label
- Read the numbers
- Description
- Use CategoryBars instead when the reader must compare exact category magnitudes side by side.
Motion Haptics
- Motion
- Label
- No intrinsic motion
- Description
- Segments do not animate on mount; a parent may transition the whole bar.
- Haptics
- Label
- No feedback
- Description
- The chart is a display and requests no haptic feedback.