Chart

Angular chart primitives and chart families inspired by shadcn Chart.

In this repository, shadcn's single Chart page maps to the dedicated /ui/chart/* demo route group so each chart family can keep focused, production-like examples without forcing everything into one /ui/shadcn/chart page.

Use Chart for dashboards, KPI cards, trend comparisons, radial summaries, and interactive data views where one shared config should drive labels, colors, legends, and tooltip copy.

Installation

bun add @edsis/chart
npm install @edsis/chart

Import

Import shared primitives from the chart root entrypoint, then import the concrete chart family from its granular subpath.

import {
  ChartAxisX,
  ChartAxisY,
  ChartContainer,
  ChartGrid,
  ChartLegend,
  ChartTooltip,
  type ChartConfig,
} from '@edsis/chart';
import { BarChart } from '@edsis/chart/bar';

Supported chart entrypoints

| Import path | Selector | Best for | | ---------------------- | -------------- | ----------------------------------------------------------------- | | @edsis/chart/bar | ChartBar | grouped, stacked, horizontal, active, and mixed-color bar layouts | | @edsis/chart/line | ChartLine | trends, comparisons, and zoomable time-series lines | | @edsis/chart/area | ChartArea | filled trend bands, stacked areas, and expanded percent views | | @edsis/chart/pie | ChartPie | part-to-whole slices and donut charts | | @edsis/chart/radar | ChartRadar | multi-axis performance comparisons | | @edsis/chart/radial | ChartRadial | progress rings, radial comparisons, and center-metric summaries | | @edsis/chart/scatter | ChartScatter | XY correlation plots and point clouds |

Composition

The Angular structure keeps the same high-level idea as shadcn Chart: define a shared chart config once, then compose a specific chart type with optional grid, axis, tooltip, legend, and center content.

chart
├── chart-bar | chart-line | chart-area | chart-scatter
│   ├── svg:g[chart-grid]
│   ├── svg:g[chart-axis-x]
│   ├── svg:g[chart-axis-y]
│   └── svg:g[chart-crosshair] / svg:g[chart-brush] (optional)
├── chart-pie | chart-radial | chart-radar
│   └── chart-pie-center | chart-radial-center (optional)
├── chart-tooltip
├── chart-legend
└── chart-zoom-controls (optional)

All child primitives read dimensions, series metadata, and scoped color tokens from Chart.

Basic usage

Start with a readonly ChartConfig, keep the dataset in any shape that makes sense for your feature, and map the chart to the relevant keys.

const trafficChartConfig = {
  desktop: { label: 'Desktop', color: 'var(--chart-1)' },
  mobile: { label: 'Mobile', color: 'var(--chart-2)' },
} satisfies ChartConfig;

const trafficData = [
  { month: 'January', desktop: 186, mobile: 80 },
  { month: 'February', desktop: 305, mobile: 200 },
  { month: 'March', desktop: 237, mobile: 120 },
  { month: 'April', desktop: 73, mobile: 190 },
  { month: 'May', desktop: 209, mobile: 130 },
  { month: 'June', desktop: 214, mobile: 140 },
];

<div class="w-full max-w-3xl">
  <Chart [config]="trafficChartConfig" chartId="traffic-overview">
    <ChartBar [data]="trafficData" xKey="month">
      <svg:g ChartGrid></svg:g>
      <svg:g ChartAxisX></svg:g>
      <svg:g ChartAxisY></svg:g>
    </ChartBar>
    <ChartTooltip [data]="trafficData" xKey="month" />
    <ChartLegend />
  </Chart>
</div>

Common patterns

First chart flow

The closest Angular equivalent to the upstream shadcn walkthrough is:

1. Define your dataset.
2. Define ChartConfig so labels and colors stay decoupled from the raw data.
3. Wrap the chart in Chart.
4. Add svg:g[ChartGrid], axis directives, ChartTooltip, and ChartLegend only where they add value.

This keeps the chart family focused while still letting the shared primitives manage the common UI pieces.

Swapping chart families

The same ChartConfig can back multiple chart families. In most cases you only swap the concrete chart import and the family-specific inputs.

import { AreaChart } from '@edsis/chart/area';
import { LineChart } from '@edsis/chart/line';

• ChartLine adds inputs such as curve, showDots, and showValueLabels.
• ChartArea adds stacked, expanded, gradient, and curve.
• ChartBar adds orientation, variant, colorKey, activeKey, and activeValue.

Pie and radial summaries

For donut, pie, and radial progress layouts, use nameKey plus valueKey instead of xKey.

<Chart [config]="browserConfig" aspect="aspect-square">
  <ChartPie
    [data]="browserData"
    nameKey="browser"
    valueKey="visitors"
    [seriesKeys]="browserSeriesKeys"
    [innerRadius]="64">
  </ChartPie>
  <ChartTooltip [data]="browserData" xKey="browser" valueKey="visitors" indicator="dot" />
  <ChartLegend />
</Chart>

Tooltip formatting

ChartTooltip is where most presentational customization lives.

<ChartTooltip
  [data]="activityData"
  xKey="date"
  indicator="line"
  labelKey="views"
  [labelFormatter]="longDateFormatter"
  [formatter]="compactNumberFormatter" />

Use valueKey for single-value radial and pie datasets, hideLabel when the card already provides the label context, and indicator="none" when you want a copy-first tooltip layout.

Per-row colors and active emphasis

Use colorKey when the dataset itself carries a color token such as fill, and use activeKey plus activeValue when one category should be visually emphasized without rewriting the whole series config.

API reference

ChartContainer

| Input | Type | Default | | --------- | ---------------- | ---------------- | | config | ChartConfig | — | | aspect | string | 'aspect-video' | | ChartId | string \| null | auto-generated |

ChartConfig is a readonly record of series keys to labels, icons, colors, or theme-aware light/dark color maps.

type ChartConfig = Readonly<
  Record<
    string,
    {
      label?: string;
      icon?: Type<unknown>;
      color?: string;
      theme?: Readonly<Record<'light' | 'dark', string>>;
    }
  >
>;

Shared primitives

| Part | Key inputs | Notes | | ------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | svg:g[ChartGrid] | none | Adds cartesian grid lines behind bar, line, and area charts. | | svg:g[ChartAxisX] | tickCount, tickLine, tickFormat | Categorical axis for cartesian layouts. | | svg:g[ChartAxisY] | tickCount, tickLine, tickFormat | Numeric axis for cartesian layouts. | | ChartTooltip | data, xKey, valueKey, indicator, label, labelKey, labelFormatter, formatter, hideLabel | Handles default tooltip layout plus custom template projection. | | ChartLegend | none | Renders toggle buttons for visible series. | | ChartZoomControls | none | Pair with zoomable line and scatter views. | | ChartPieCenter | projected content | Centers labels or KPIs inside pie layouts. | | ChartRadialCenter | projected content | Centers labels or KPIs inside radial layouts. |

Chart families

| Selector | Key inputs | | -------------- | --------------------------------------------------------------------------------------------------- | | ChartBar | data, xKey, orientation, variant, colorKey, activeKey, activeValue, showValueLabels | | ChartLine | data, xKey, curve, showDots, dotRadius, showValueLabels | | ChartArea | data, xKey, stacked, expanded, gradient, curve | | ChartPie | data, nameKey, valueKey, seriesKeys, innerRadius, activeIndex, activeOffset | | ChartRadar | data, axisKey, curve, levels, grid, showLabels, showDots | | ChartRadial | data, nameKey, valueKey, seriesKeys, maxValue, showTrack, showValueLabels | | ChartScatter | data, xKey, yKey, sizeKey, seriesKey, xDomain, yDomain |

Styling and theming

• Prefer CSS variables such as var(--chart-1) and var(--chart-2) in ChartConfig. This matches the current shadcn guidance and the theme tokens shipped by this library.
• Chart scopes generated --color-<series> variables to the chart instance, so tooltip rows, legends, and series shapes stay aligned.
• Use theme: { light, dark } on a series config entry when the chart needs different values per color scheme.
• Keep the parent container responsible for width, and use the aspect input when the default aspect-video does not match the layout.
• Use colorKey only when the dataset should override per-series colors with a row-specific token such as fill.

Accessibility

• Chart hosts expose an aria-label summary describing the chart type, category count, and visible series.
• Interactive marks such as bars, dots, and slices are keyboard focusable where the layout supports activation.
• ChartTooltip includes a polite live region so changing categories can be announced to assistive technology.
• ChartLegend uses native buttons with aria-pressed to reflect hidden and visible series state.
• Keep surrounding card copy descriptive so the chart has enough context when read outside its visual layout.

Keyboard interactions

• Tab reaches interactive bars, dots, slices, and legend toggle buttons.
• Enter and Space trigger the same click behavior as pointer activation on interactive marks.
• Focusing a supported data mark updates the shared active point so tooltip content stays reachable without hover.

Angular notes

• Keep chart config objects readonly and signal-friendly. A top-level const or signal-backed computed config works well.
• Every chart family must live inside Chart; that container provides dimensions, series visibility state, and scoped color variables to descendants.
• Use an explicit ChartId when multiple charts of the same family appear on one page or when tests need a stable selector.
• The local shadcn mapping for Chart lives in the dedicated /ui/chart overview route with focused family demos under /ui/chart/*.

Source parity

This Angular package follows the shadcn Chart information architecture and theming concepts, but it does not mirror the React API one-to-one.

• shadcn uses Recharts components directly and layers ChartTooltipContent and ChartLegendContent around them.
• This Angular library ships standalone chart families plus shared primitives, so you compose Chart, the relevant chart-*, ChartTooltip, and ChartLegend instead of wiring Recharts JSX.
• The dedicated /ui/chart/* route group is the intentional local mapping for shadcn Chart in this repo; no duplicate /ui/shadcn/chart page is required.