Cloaked Design SystemVisualizations

BarChart

Vertical bars over an ordered sequence, the interactive chart member: an optional drag or keyboard scrubber plus a range toggle, with single-value or stacked bars.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

6 stories

Interactive selectedOpen canvas

Example source

packages/design-system/src/components/visualizations/BarChart/BarChart.stories.tsxExport Interactive

Implementation 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.

Vertical bars over an ordered sequence, the interactive chart member: an optional drag or keyboard scrubber plus a range toggle, with single-value or stacked bars.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

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 { BarChart } from '@cloakedinc/design-system';

BarChartBarChartProps<TPeriod>

packages/design-system/src/components/visualizations/BarChart/BarChart.tsx:22

Prop	Type	Presence	Notes
`values`	`number[]`	Required	Bar values rendered in order.
`stacks`	`readonly BarChartStack[] \| undefined`	Optional	Optional stacked segments rendered instead of a single value bar.
`periods`	`readonly DataVisualizationPeriod<TPeriod>[] \| undefined`	Optional	Optional period controls shown with the chart.
`activePeriod`	`TPeriod \| undefined`	Optional	Id of the period button shown as selected; leave unset for none.
`onPeriodChange`	`((period: TPeriod) => void) \| undefined`	Optional	Fires with the tapped period id — the chart never changes `values` itself.
`onScrubStart`	`(() => void) \| undefined`	Optional	Fires once when a scrub session begins. Passing any of the three scrub handlers is what turns the plot into a focusable slider.
`onScrub`	`((index: number, value: number) => void) \| undefined`	Optional	Called with the active bar index and value while scrubbing.
`onScrubEnd`	`(() => void) \| undefined`	Optional	Fires once when the session ends — pointer up, cancel, or blur — not on every move.
`ariaLabel`	`string \| undefined`	Optional	Accessible label for meaningful charts.
`testId`	`string \| undefined`	Optional	Optional test selector. The plot derives `${testId}-plot` and each period button `${testId}-period-<lowercased id>`.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

Vertical bars over an ordered sequence — almost always time buckets — and the one interactive member of the chart family.

When to use

Use BarChart for a series of discrete values across an ordered x-axis (days, weeks) where the reader may want to inspect individual buckets. It is the only chart here that supports scrubbing: pass onScrub/onScrubStart/onScrubEnd to make the plot a drag/keyboard slider, and periods + activePeriod + onPeriodChange for a range toggle (1M / 6M / 1Y / All). Use stacks for a per-bar categorical breakdown summed bottom-to-top.

Prefer LineChart for a smooth continuous trend or many overlaid series, CategoryBars for a handful of labeled categories with readable values, and ActionOrbs for a loose proportional 2-4 category summary.

Used on Playlist Home in ActionsDetail ("Actions taken over time") as a scrubber with a period toggle.

Stacked breakdown

Each bar can be a stacks breakdown; segment color drives each band.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: plot
Label: Plot
Description: The SVG bar field that fills the container width.
Required: true

Id: track
Label: Bar track
Description: The full-height rail behind each bar.

Id: bar
Label: Bar value
Description: The value bar or stacked segments rising from the baseline.

Id: period-controls
Label: Period controls
Description: The optional range-toggle buttons shown below the plot.

Allowed Design Choices

Variants

Base

Label: Base
Description: Values, stacks, and scrub callbacks change the reading without changing the plot treatment.

Sizes

Variants

Id: base
Label: Base
Description: A vertical bar field with optional period controls and scrub callbacks.
Platforms: ios
android
web

Sizes

None specified

Measurements

Id: chart-gap
Label: Plot-to-controls gap
Kind: exact
Token: --cds-space-12
Value: 12
Unit: px
Applies To: plot
period-controls

Id: period-radius
Label: Period button radius
Kind: exact
Token: --cds-radius-lg
Value: 20
Unit: px
Applies To: period-controls

Id: period-gap
Label: Period button gap
Kind: exact
Token: --cds-space-8
Value: 8
Unit: px
Applies To: period-controls

Layout

Alignment: Bars fill the plot width evenly; period controls center below the plot.
Flow: The plot stacks above the optional period controls.
Notes: Bar geometry is drawn in SVG view-box units so the plot scales to fill the container width.

Typography And Color

Typography

Label: Period control
Description: Period toggle labels use the body ramp.
Token: --cds-type-body-size

Colors

Label: Track
Description: The rail behind each bar.
Token: --cds-graph-bg

Label: Bar value
Description: The default value-bar fill.
Token: --cds-text-primary

Label: Active bar
Description: The scrubbed bar and active track highlight.
Token: --cds-brand

Label: Active period text
Description: The selected period button ink on its filled pill.
Token: --cds-bg-page

States

Id: static
Label: Static
Description: With no scrub callbacks the plot is a presentational or labeled image.

Id: interactive
Label: Interactive
Description: Any scrub callback turns the plot into a draggable, keyboardable slider.

Id: stacked
Label: Stacked
Description: Each bar is a stack of segments summed bottom to top.

Id: empty
Label: Empty
Description: No values renders empty tracks only.

Behavior

Label: Interactive when scrubbable
Description: Passing any scrub callback switches the plot to a slider role with arrow-key support.

Label: Range toggle
Description: periods, activePeriod, and onPeriodChange add a range toggle beneath the plot.

Label: Derived test ids
Description: The scrubber and period buttons derive their test ids from the root testId.

Accessibility

Label: Static label
Description: Pass an accessible label so a static plot is announced as a meaningful image.

Label: Slider semantics
Description: When interactive the plot exposes slider min, max, current index, and a value text, and keeps an accessible name from ariaLabel with a default scrubber label as fallback.

Label: Keyboard scrubbing
Description: The interactive plot is focusable and moves the active bar with arrow keys.

Content Adaptation

Label: Time buckets
Description: Use BarChart for an ordered sequence, almost always time buckets; use CategoryBars for named categories.

Label: Stacked breakdown
Description: Use stacks for a per-bar category breakdown summed bottom to top.

Motion Haptics

Motion

Label: Active transition
Description: Bars ease their active and inactive treatment while scrubbing; no mount animation.

Haptics

Label: No feedback
Description: The chart requests no haptic feedback; a consumer may add it around scrub events.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1