Data displayGlass surface

BarChart

Compares categorical or discrete-period values with grouped and stacked bars.

View preview API reference View in Figma

FrameworksAstro · React · Elements

Registry commandlumen add BarChart

InteractionEnhanced runtime

Design sourceLinked component node

← All chart guides · Framework setup · Native counterparts

See it and copy it

Framework example

Explore the live chart, then open its code for Astro, React, or Elements.

Package downloads

View chart data

Category	Downloads
Lumen	18,420 downloads
Astro Doctor	9,870 downloads
Quality	6,320 downloads
Dep Beacon	4,210 downloads

Illustrative package download totals.

View BarChart code

Framework usage

Switch targets to compare the adapter code. This live preview runs the Astro example. React and Elements use their own behavior APIs; complete the matching framework setup before copying an example.

---
import { BarChart } from '@santi020k/lumen-astro'

const series = [
  {
    data: [
      { label: '18,420 downloads', x: 'Lumen', y: 18420 },
      { label: '9,870 downloads', x: 'Astro Doctor', y: 9870 },
      { label: '6,320 downloads', x: 'Quality', y: 6320 },
      { label: '4,210 downloads', x: 'Dep Beacon', y: 4210 }
    ],
    id: 'downloads',
    label: 'Downloads'
  }
]
---

<BarChart
  aria-label="Package downloads by project"
  caption="Illustrative package download totals."
  heading="Package downloads"
  orientation="horizontal"
  {series}
/>

import { BarChart } from '@santi020k/lumen-react'

const series = [
  {
    data: [
      { label: '18,420 downloads', x: 'Lumen', y: 18420 },
      { label: '9,870 downloads', x: 'Astro Doctor', y: 9870 },
      { label: '6,320 downloads', x: 'Quality', y: 6320 },
      { label: '4,210 downloads', x: 'Dep Beacon', y: 4210 }
    ],
    id: 'downloads',
    label: 'Downloads'
  }
]

export const Example = () => (
  <>
    <BarChart
      aria-label="Package downloads by project"
      caption="Illustrative package download totals."
      heading="Package downloads"
      orientation="horizontal"
      series={series}
    />
  </>
)

<script type="module">
  import { defineLumenElements } from '@santi020k/lumen-elements/define'

  defineLumenElements(['BarChart'])
</script>

<lumen-bar-chart id="example-bar-chart"
  aria-label="Package downloads by project"
  caption="Illustrative package download totals."
  heading="Package downloads"
  orientation="horizontal"></lumen-bar-chart>

<script type="module">
"use strict";
const series = [
    {
        data: [
            { label: '18,420 downloads', x: 'Lumen', y: 18420 },
            { label: '9,870 downloads', x: 'Astro Doctor', y: 9870 },
            { label: '6,320 downloads', x: 'Quality', y: 6320 },
            { label: '4,210 downloads', x: 'Dep Beacon', y: 4210 }
        ],
        id: 'downloads',
        label: 'Downloads'
    }
];

const chart = document.getElementById('example-bar-chart')

chart?.setAttribute('series', JSON.stringify(series))
</script>

Edit BarChart in browser

Framework differences

Elements: Pass series as a JSON attribute or through the public element property. The Elements example serializes the sample data with JSON.stringify; Astro expression bindings are not HTML attributes.

When to use BarChart

Use for category totals, rankings, or comparing the same measures across a small set of named groups.

Use horizontal orientation when category names need more room. Grouped bars emphasize comparisons between series; stacked bars emphasize totals and contributions.
Positive and negative values stack separately around zero. Keep the legend and exact-data disclosure available when multiple series share a category.

Prepare the data

import type { LumenChartSeries } from '@santi020k/lumen-core'

const series = [{
  id: 'downloads',
  label: 'Downloads',
  data: [
    { x: 'lumen', xLabel: 'Lumen', y: 18420 },
    { x: 'quality', xLabel: 'Quality', y: 6320 }
  ]
}] satisfies readonly LumenChartSeries[]

Aggregate source records before passing series. Each series needs a unique id, label, and at most one observation for each category identity.
Reuse the same x identities across series to align categories. Use xLabel for display text and null for unavailable measurements.

Shared data and formatting guidance →

Avoid misleading comparisons

Stack only quantities whose sum is meaningful. Percentages with different denominators are not additive.
A bar encodes magnitude through length. Preserve a zero baseline when configuring scales through lower-level chart tools.

Chart accessibility and keyboard guidance →

Choose your target

Add this component

Choose the package for your runtime. All adapters share the Lumen stylesheet. Use the matching registry command when you want a local wrapper for that framework.

pnpm add @santi020k/lumen-astro

pnpm add @santi020k/lumen-astro

lumen add BarChart

lumen add BarChart

pnpm add @santi020k/lumen-react

pnpm add @santi020k/lumen-react

lumen add BarChart --target react

lumen add BarChart --target react

pnpm add @santi020k/lumen-elements

pnpm add @santi020k/lumen-elements

lumen add BarChart --target elements

lumen add BarChart --target elements

Glass

Add the glass prop to apply the shared blur, saturation, border, and highlight tokens. Glass reads best over vivid content, so place the surface above imagery or color.

Pipeline duration

View chart data

Category	Minutes
Build	18
Test	11
Deploy	7

View BarChart code

Framework usage

Switch targets to compare the adapter code. This live preview runs the Astro example. React and Elements use their own behavior APIs; complete the matching framework setup before copying an example.

---
import { BarChart } from '@santi020k/lumen-astro'

const series = [
  {
    data: [
      { x: 'Build', y: 18 },
      { x: 'Test', y: 11 },
      { x: 'Deploy', y: 7 }
    ],
    id: 'minutes',
    label: 'Minutes'
  }
]
---

<div class="docs-glass-demo">
  <BarChart
    aria-label="Pipeline duration"
    glass
    heading="Pipeline duration"
    {series}
  />
</div>

import { BarChart } from '@santi020k/lumen-react'

const series = [
  {
    data: [
      { x: 'Build', y: 18 },
      { x: 'Test', y: 11 },
      { x: 'Deploy', y: 7 }
    ],
    id: 'minutes',
    label: 'Minutes'
  }
]

export const Example = () => (
  <>
    <div className="docs-glass-demo">
      <BarChart
        aria-label="Pipeline duration"
        glass
        heading="Pipeline duration"
        series={series}
      />
    </div>
  </>
)

<script type="module">
  import { defineLumenElements } from '@santi020k/lumen-elements/define'

  defineLumenElements(['BarChart'])
</script>

<div class="docs-glass-demo">
  <lumen-bar-chart id="example-bar-chart"
    aria-label="Pipeline duration"
    glass
    heading="Pipeline duration"></lumen-bar-chart>
</div>

<script type="module">
"use strict";
const series = [
    {
        data: [
            { x: 'Build', y: 18 },
            { x: 'Test', y: 11 },
            { x: 'Deploy', y: 7 }
        ],
        id: 'minutes',
        label: 'Minutes'
    }
];

const chart = document.getElementById('example-bar-chart')

chart?.setAttribute('series', JSON.stringify(series))
</script>

Edit BarChart in browser

API reference

Lumen-specific props and runtime attributes for the Astro primitive. Use the framework differences above and the copyable examples for React composition and Elements attributes; the public adapter types define their supported contracts.

Attribute	Values	Default	Description
glass	boolean \| "subtle" \| "strong"	false	Applies the tokenized liquid-glass surface treatment with backdrop-filter fallbacks; "subtle" and "strong" adjust the fill intensity.
drilldown	boolean (Astro / Elements attribute)	false	Enables plotted datum actions and an equivalent native button disclosure, including with hidden tables. Astro requires UIPrimitives; Elements owns its lifecycle.
onDatumActivate	(detail: LumenChartDatumActivationDetail) => void (React)	-	Enables React datum actions and receives validated values with raw identities. Navigation and filtering remain application owned.
explore-data-label, datum-action-prefix, datumActionFormatter	string attributes, (context: string) => string property (Elements)	English labels	Localizes the Elements disclosure and datum actions.
labels.exploreData, labels.formatDatumAction	string, (context: string) => string	English labels	Localizes the actions disclosure and each contextual datum button.
series	LumenChartSeries[]	required	Provides already-aggregated categorical values and stable series metadata.
orientation	"horizontal" \| "vertical"	"vertical"	Controls whether values extend across the x or y axis.
layout	"grouped" \| "stacked"	"grouped"	Places series beside one another or combines their positive and negative totals.
categoryWidth	number	160	Reserves 64–240 SVG units for horizontal category labels.
formatCategory, formatValue	formatter functions	String	Formats axes, SVG titles, and the accessible data table without changing data identity.
emptyLabel	string	"No chart data available."	Provides actionable, source-specific empty-state guidance.
showLegend	boolean	true for multiple series	Shows the color-independent series key.
showTable	boolean	true	Provides a revealable semantic table containing every plotted value.
heading, description, caption	string	-	Adds visible chart context without replacing the accessible name.
class, className	string	""	Merges custom classes with the generated ui-* root classes.
...native attributes	HTML attributes	-	Forwards standard attributes to the root element unless the component consumes them.

Keyboard interactions

Keyboard behavior provided by the Astro UIPrimitives runtime for this component.

Key	Action
Tab	Focus the actions disclosure and its native buttons in document order.
Enter, Space	Toggle the disclosure or activate the focused datum button. Actions remain available when the data table is hidden.

Runtime events

CustomEvents dispatched by the Astro UIPrimitives runtime for this component.

Event	Target	Detail	When
ui:chart-datum-activate	Astro chart figure or Elements data chart host	LumenChartDatumActivationDetail: series { seriesId, x, y, datumId? }, heatmap { x, y, value, datumId? }, range { x, low, high, datumId? }	Fires once after a plotted datum or its native action button is activated. Requires drilldown. Astro uses UIPrimitives, Elements owns its lifecycle, and React uses onDatumActivate instead.