Chart New Alpha

Usage

Chart is a framework-independent Lit implementation of the compositional design used by shadcn-vue Chart. A Chart owns data and shared series configuration; axes, marks, tooltip, crosshair and legend are separate custom elements that describe what to render.

Import Chart and only the parts used by the composition. Each import registers one custom element:

import "@nordhealth/components/lib/Chart"
import "@nordhealth/components/lib/ChartAxis"
import "@nordhealth/components/lib/ChartLine"
import "@nordhealth/components/lib/ChartTooltip"
import "@nordhealth/components/lib/ChartCrosshair"
import "@nordhealth/components/lib/ChartLegend"

Other marks have their own entries, so a grouped bar chart can import ChartGroupedBar without importing ChartStackedBar, ChartLine, ChartArea, ChartPie or ChartDonut.

import "@nordhealth/components/lib/ChartArea"
import "@nordhealth/components/lib/ChartDonut"
import "@nordhealth/components/lib/ChartGroupedBar"
import "@nordhealth/components/lib/ChartPie"
import "@nordhealth/components/lib/ChartStackedBar"

Chart uses Unovis internally for rendering. You do not need to install or import Unovis. After a connected Chart has a label, data, config and valid composition, it lazily loads only the Unovis container, marks and helpers required by that composition. Importing Chart or another Nord component does not load the renderer. If the composition changes while loading is pending, Chart discards that stale request and renders only the latest valid revision.

Then compose the parts inside a Chart:

Composition

A Chart contains either one or more Cartesian marks, or one circular mark. Cartesian compositions can add axes, a tooltip, a crosshair and a legend. Circular compositions can add a tooltip and legend, but not axes or a crosshair. The required label becomes the accessible name of the rendered figure.

Chart
├── ChartAxis × 0–2                                (Cartesian only)
├── ChartGroupedBar | ChartStackedBar              (Cartesian marks)
│   | ChartLine | ChartArea
├── ChartPie | ChartDonut × 1                      (circular alternative)
├── ChartTooltip × 0–1
├── ChartCrosshair × 0–1                           (Cartesian; requires tooltip)
├── ChartLegend × 0–1
├── summary slot                                   (complete accessible alternative)
└── empty slot                                     (empty-data content)

Chart follows shadcn's configuration model. Assign a JavaScript-only .config record whose keys identify series or circular categories. Each item can provide a label, Nord icon name and either one color or a light/dark theme pair. TypeScript consumers can import the exported ChartConfig type from @nordhealth/components.

Items without a configured color use a theme-aware 17-color palette for Cartesian series or a five-color segmentation palette for pie and donut categories. Customize the defaults with --n-chart-color-1 through --n-chart-color-17 and --n-chart-segmentation-color-1 through --n-chart-segmentation-color-5.

const config = {
  desktop: {
    label: "Desktop",
    theme: {
      light: "var(--n-color-accent)",
      dark: "var(--n-color-status-highlight)",
    },
  },
  mobile: {
    label: "Mobile",
    color: "var(--n-color-status-info)",
  },
}

Compose the visible structure in HTML. Functions and arrays are JavaScript properties, so assign them after creating plain custom elements or use the property-binding syntax provided by Lit, Vue, React, Angular or another framework.

<nord-chart label="Monthly visits">
  <nord-chart-axis type="x" label="Month"></nord-chart-axis>
  <nord-chart-axis type="y" label="Visits"></nord-chart-axis>
  <nord-chart-line></nord-chart-line>
  <nord-chart-tooltip></nord-chart-tooltip>
  <nord-chart-crosshair></nord-chart-crosshair>
  <nord-chart-legend></nord-chart-legend>
  <table slot="summary"><!-- Complete data table. --></table>
  <p slot="empty">No visits available.</p>
</nord-chart>

Assign the shared config and immutable rows, then pass direct accessors to the mark and helpers. Reassign a new data array whenever rows change; in-place mutations are not observed.

const chart = document.querySelector("nord-chart")
const line = chart.querySelector("nord-chart-line")
const xAxis = chart.querySelector('nord-chart-axis[type="x"]')
const tooltip = chart.querySelector("nord-chart-tooltip")

const month = row => row.month
const desktop = row => row.desktop
const mobile = row => row.mobile

chart.config = config
chart.data = [
  { month: "January", desktop: 186, mobile: 80 },
  { month: "February", desktop: 305, mobile: 200 },
]
line.x = month
line.y = [desktop, mobile]
line.keys = ["desktop", "mobile"]
xAxis.x = month
tooltip.label = month

For a single series, .y can be one accessor instead of an array. When .keys is omitted, Chart pairs the first config key with a single y accessor, or the first N config keys with N accessors. Explicit keys must exist in config and match the accessor count. A mark's optional .color property overrides config colors for that mark only.

Invalid compositions fail closed before Unovis loads and report stable NORD_CHART_* errors once per unchanged revision. The individual entries are SSR-safe and do not evaluate the renderer or read browser globals when imported.

Examples

Grouped bars

Chart Grouped Bar compares multiple values side by side. Assign one .x accessor, one .y accessor or accessor array, and optional matching .keys. Bars default to the 3px radius of --n-border-radius-s and 0.02 (2%) fractional padding; set rounded-corners, bar-padding, and group-padding to tune their shape and spacing. Set orientation="horizontal" when values should extend inline from each category.

Chart Axis requires type="x" or type="y". Assign the matching .x or .y accessor when an explicit scale is needed; an x axis otherwise inherits the first mark's x accessor. Use .tickValues and .tickFormat to customize ticks, hide-grid-lines to remove its grid and label for the visible title.

Stacked bars

Chart Stacked Bar displays each series as a contribution to a total. It uses the same .x, .y, .keys, .color, orientation, rounded-corners and bar-padding contract as grouped bars, but has a separate import so grouped and stacked code are never loaded together unless both are used. A one-row stacked composition with orientation="horizontal" creates a single proportionally split bar.

Line chart

Chart Line shows change over an ordered Cartesian scale. Assign .x, .y and optional .keys directly; config supplies the corresponding labels, icons and colors. Add show-points to render a marker at every data value. Its small Scatter renderer module is loaded only for line compositions that request points.

Chart Tooltip adds supplementary pointer content using config metadata. Its optional .label accessor supplies the heading, while .labelFormatter and .valueFormatter format safe text. Choose a dot, line or dashed indicator, or use hide-label and hide-indicator. A successful formatter result of null or undefined omits that content, numeric zero is preserved, and a throwing formatter falls back to the raw value.

Chart Crosshair adds Cartesian pointer interaction and requires a Chart Tooltip.

Area chart

Chart Area emphasizes magnitude as well as change. It uses the same .x, .y, .keys and .color properties as Chart Line. Set opacity between 0 and 1, and add hide-line to remove the area boundary.

Pie chart

Chart Pie shows a small part-to-whole comparison. Assign a .category accessor that returns a config key and a numeric .value accessor. Config insertion order controls stable labels, icons and colors unless the mark supplies a .color override.

Chart Legend renders config items as a semantic list. Use placement="block-start" to move it above the plot, hide-icons to remove icons and swatches, or assign .keys to show a subset in a specific order. Add toggleable to render accessible toggle buttons that show or hide a series; Chart always keeps at least one series visible. When config omits a color, Chart assigns --n-chart-color-1 through --n-chart-color-8 in stable config order.

Donut chart

Chart Donut uses the same .category, .value and .color properties as Chart Pie. It additionally requires a positive arc-width; central-label and central-sub-label add text to its centre.

Accessibility

• Give every Chart a concise, non-empty label so its figure has an accessible name.
• Add prose or a semantic <table slot="summary"> containing every category, series and value represented visually. The empty slot provides content when .data has no rows.
• Treat the tooltip, crosshair and legend as supplementary; they are not replacements for the complete summary.
• Keep visible config labels and the summary so color is never the only carrier of meaning.
• When prefers-reduced-motion: reduce matches, Chart uses zero-duration animation for initial rendering, data updates and structural replacements.
• Chart fills its available inline size and follows the active Nord color scheme. Reassign .data to publish an update without rebuilding the composition.
• Chart does not perform aggregation or downsampling. Prepare dense data before assignment, preserve important extrema and total meaning, and include the summarized values in the accessible table.