Data display

ComboChart

Combines bars, lines, and areas on one meaningful shared value domain.

View preview API reference Figma behavior note

FrameworksAstro · React · Elements

Registry commandlumen add ComboChart

InteractionEnhanced runtime

Design sourceBehavior-only contract

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

A stronger second half

Paid orders · January–August 2026

Paid orders
Monthly plan

View chart data

Category	Paid orders	Monthly plan
Jan	128	140
Feb	146	150
Mar	138	165
Apr	192	180
May	176	195
Jun	218	210
Jul	246	230
Aug	274	250

Bars show actual orders; the line shows the plan on the same scale. August finished 24 orders ahead. Illustrative data.

View ComboChart 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 { ComboChart } from '@santi020k/lumen-astro'
import type { LumenComboSeries } from '@santi020k/lumen-core'

const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug']

const series = [
  {
    id: 'orders',
    label: 'Paid orders',
    mark: 'bar',
    tone: 'series-1',
    data: [128, 146, 138, 192, 176, 218, 246, 274].map((y, index) => ({ x: months[index] ?? '', y }))
  },
  {
    id: 'plan',
    label: 'Monthly plan',
    mark: 'line',
    tone: 'series-3',
    data: [140, 150, 165, 180, 195, 210, 230, 250].map((y, index) => ({ x: months[index] ?? '', y }))
  }
] satisfies readonly LumenComboSeries[]
---

<ComboChart
  aria-label="Monthly paid orders compared with plan"
  heading="A stronger second half"
  description="Paid orders · January–August 2026"
  caption="Bars show actual orders; the line shows the plan on the same scale. August finished 24 orders ahead. Illustrative data."
  {series}
/>

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

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

const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug']

const series = [
  {
    id: 'orders',
    label: 'Paid orders',
    mark: 'bar',
    tone: 'series-1',
    data: [128, 146, 138, 192, 176, 218, 246, 274].map((y, index) => ({ x: months[index] ?? '', y }))
  },
  {
    id: 'plan',
    label: 'Monthly plan',
    mark: 'line',
    tone: 'series-3',
    data: [140, 150, 165, 180, 195, 210, 230, 250].map((y, index) => ({ x: months[index] ?? '', y }))
  }
] satisfies readonly LumenComboSeries[]

export const Example = () => (
  <>
    <ComboChart
      aria-label="Monthly paid orders compared with plan"
      heading="A stronger second half"
      description="Paid orders · January–August 2026"
      caption="Bars show actual orders; the line shows the plan on the same scale. August finished 24 orders ahead. Illustrative data."
      series={series}
    />
  </>
)

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

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

<lumen-combo-chart id="example-combo-chart"
  aria-label="Monthly paid orders compared with plan"
  heading="A stronger second half"
  description="Paid orders · January–August 2026"
  caption="Bars show actual orders; the line shows the plan on the same scale. August finished 24 orders ahead. Illustrative data."></lumen-combo-chart>

<script type="module">
const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug'];
const series = [
    {
        id: 'orders',
        label: 'Paid orders',
        mark: 'bar',
        tone: 'series-1',
        data: [128, 146, 138, 192, 176, 218, 246, 274].map((y, index) => ({ x: months[index] ?? '', y }))
    },
    {
        id: 'plan',
        label: 'Monthly plan',
        mark: 'line',
        tone: 'series-3',
        data: [140, 150, 165, 180, 195, 210, 230, 250].map((y, index) => ({ x: months[index] ?? '', y }))
    }
];
export {};

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

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

Edit ComboChart 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 ComboChart

Use when different mark styles help distinguish related measures that share a unit, such as revenue and profit in the same currency.

The mark type distinguishes each measure without requiring color alone. Keep the series legend and a caption explaining the marks.
All marks use one value domain. formatValue applies the same units to the shared chart and data alternative.

Prepare the data

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

const series = [
  {
    id: 'revenue', label: 'Revenue', mark: 'bar',
    data: [{ x: 'Q1', y: 128 }, { x: 'Q2', y: 154 }]
  },
  {
    id: 'profit', label: 'Profit', mark: 'line',
    data: [{ x: 'Q1', y: 42 }, { x: 'Q2', y: 49 }]
  }
] satisfies readonly LumenComboSeries[]

Each series has a unique id, label, and mark of bar, line, or area. Points use the shared x/y datum contract.
Matching category identities align the marks. Use null for missing observations and keep all series in the same numeric unit.

Shared data and formatting guidance →

Avoid misleading comparisons

There is no secondary-axis prop. Do not plot currency and percentage rates together as if their numeric magnitudes were comparable.
A series with much smaller values can disappear against a larger series. Use separate charts when the shared scale hides the question.

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 ComboChart

lumen add ComboChart

pnpm add @santi020k/lumen-react

pnpm add @santi020k/lumen-react

lumen add ComboChart --target react

lumen add ComboChart --target react

pnpm add @santi020k/lumen-elements

pnpm add @santi020k/lumen-elements

lumen add ComboChart --target elements

lumen add ComboChart --target elements

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
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	LumenComboSeries[]	[]	Combines bar and line series over one ordered category domain.
formatValue	(value: number) => string	String	Formats visible values and the accessible summary without changing source data.
showLegend	boolean	true	Shows the color-independent series key.
showTable	boolean	true	Provides a revealable semantic table containing every plotted value.
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.

Category	Paid orders	Monthly plan
Jan	128	140
Feb	146	150
Mar	138	165
Apr	192	180
May	176	195
Jun	218	210
Jul	246	230
Aug	274	250

Category	Paid orders	Monthly plan
Jan	128	140
Feb	146	150
Mar	138	165
Apr	192	180
May	176	195
Jun	218	210
Jul	246	230
Aug	274	250