CategoryBars
Horizontal labeled bars for a ranked breakdown of a handful of named categories with their counts visible, the read-the-numbers chart in the family.
Implementation previewEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Example source
packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.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.
Horizontal labeled bars for a ranked breakdown of a handful of named categories with their counts visible, the read-the-numbers chart in the family.
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 { CategoryBars } from '@cloakedinc/design-system';CategoryBarsCategoryBarsProps
packages/design-system/src/components/visualizations/CategoryBars/CategoryBars.tsx:12
| Prop | Type | Presence | Notes |
|---|---|---|---|
items | readonly CategoryDatum[] | Required | Category rows rendered in 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
Horizontal labeled bars — a ranked breakdown of a handful of named categories with their counts visible.
When to use
This is the "read the actual numbers" chart: reach for it when the reader must compare the
magnitudes of a small set of named categories and see the exact counts. Each row takes its
color; omit color and rows cycle the default category palette.
Prefer it over ActionOrbs (a looser proportional 2-4 category summary) and
BubbleMatrix/BurstGraph (decorative) whenever precision matters. Use BarChart instead when
the x-axis is time rather than categories.
Not currently used in the app.
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- list
- Label
- List
- Description
- The column of category rows.
- Required
- true
- Id
- row
- Label
- Row
- Description
- A label, track, and value aligned in a three-column grid.
- Id
- track
- Label
- Track
- Description
- The rail whose fill length scales to the category value.
- Id
- value
- Label
- Value
- Description
- The right-aligned numeric count for the row.
Allowed Design Choices
- Variants
- Base
- Label
- Base
- Description
- Category data changes the reading without changing the row treatment.
- Sizes
Variants
- Id
- base
- Label
- Base
- Description
- A column of labeled category rows with proportional bars and counts.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- track-height
- Label
- Track height
- Kind
- exact
- Token
- --cds-size-4
- Value
- 4
- Unit
- px
- Applies To
- track
- Id
- row-gap
- Label
- Row gap
- Kind
- exact
- Token
- --cds-space-12
- Value
- 12
- Unit
- px
- Applies To
- list
- Id
- column-gap
- Label
- Row column gap
- Kind
- exact
- Token
- --cds-space-8
- Value
- 8
- Unit
- px
- Applies To
- row
Layout
- Alignment
- Each row is a label, a stretching track, and a right-aligned value in a three-column grid.
- Flow
- Rows stack top to bottom in a column.
- Notes
- The track column stretches while the label and value columns size to content.
Typography And Color
- Typography
- Label
- Row label and value
- Description
- The category label and count use the body ramp.
- Token
- --cds-type-body-size
- Colors
- Label
- Row label and value
- Description
- Label and count use primary text.
- Token
- --cds-text-primary
- Label
- Track
- Description
- The unfilled rail behind each bar.
- Token
- --cds-bg-page
States
- Id
- ranked
- Label
- Ranked
- Description
- Rows render in order with bars scaled to the largest value.
- Id
- default-palette
- Label
- Default palette
- Description
- Rows without a color cycle the built-in category palette.
- Id
- empty
- Label
- Empty
- Description
- No rows renders nothing, so pair with an upstream empty state.
Behavior
- Label
- Scaled to max
- Description
- Bar length scales to the largest category value in the set.
- Label
- Palette fallback
- Description
- Rows take their own color, or cycle the default category palette when none is given.
- Label
- Readable counts
- Description
- Each row shows its formatted numeric count beside the bar.
Accessibility
- Label
- Meaningful chart
- Description
- Pass an accessible label so the row set is announced as a meaningful image.
- Label
- Track is presentational
- Description
- The bar track is hidden from assistive technology since the label and count carry the meaning.
Content Adaptation
- Label
- Read the numbers
- Description
- Use CategoryBars when the reader must compare category magnitudes with the actual counts visible.
- Label
- Categories over time
- Description
- Use BarChart instead when the x-axis is time rather than named categories.
Motion Haptics
- Motion
- Label
- No intrinsic motion
- Description
- The rows do not animate on mount; a parent may transition the whole chart.
- Haptics
- Label
- No feedback
- Description
- The chart is a display and requests no haptic feedback.