mielui
Chart components

Chart

Bar, line, and area charts built from composable marks.

Installation

pnpm dlx @mielui/svelte add chart

Usage

Root takes data, config, and x, the field that holds each category. Each config entry gives a numeric series a label, a color, and an optional value formatter. Match each mark's key to its data field and config entry.

Plot sets up the scales. Put Grid, XAxis, YAxis, and the marks inside it. Place Legend and Tooltip directly inside Root; either can move or be left out.

String categories use equal spacing. Numeric and Date categories retain their relative distance. Sort time-series data before rendering. Null, missing, and non-finite numeric values leave gaps.

<script lang="ts">
    import * as Chart from '@mielui/svelte/components/chart';

    const data = [
        { month: 'Jan', revenue: 186, target: 160 },
        { month: 'Feb', revenue: 242, target: 190 }
    ];
    const config = {
        revenue: { label: 'Revenue' },
        target: { label: 'Target' }
    };
</script>

<Chart.Root {data} {config} x="month" aria-label="Monthly revenue and target">
    <Chart.Legend />
    <Chart.Plot>
        <Chart.Grid />
        <Chart.XAxis />
        <Chart.YAxis />
        <Chart.Bar key="revenue" />
        <Chart.Line key="target" />
    </Chart.Plot>
    <Chart.Tooltip />
</Chart.Root>

Chart types

Bar chart

Compare categories with grouped or stacked bars.

Line chart

Follow changes over time without a filled area.

Area chart

Show the amount over time with a filled series.

Mixed chart

Compare totals and benchmarks in one plot.

Loading and empty data

Set loading on Root while a request is pending. The chart keeps its height and shows a neutral skeleton. An empty dataset shows an empty state; pass an empty snippet to Plot to replace it. Try each state below.

Animation

The default reveal animation runs on entry, and data changes transition from the current display. Set animation="live" for a highlight that travels along lines, sweeps through areas, and rises through bars, with pauses between passes. Highlights hide while you inspect values, and motion pauses offscreen or when the tab is hidden. Set animation="none" to turn chart motion off.

Chart motion follows reduced-motion preferences and the theme's motion setting. Every chart-type guide includes a live example to compare the effect on different marks. Tooltips share their surface with pie and heatmap tooltips, follow the theme's glass setting, and sit beside the pointer.

Accessibility

Give Root a descriptive aria-label; it is required. Root includes a data table for screen readers. With Tooltip present, Tab reaches the categories once, and arrow keys, Home, and End move between them to inspect the same values a pointer shows. Escape dismisses the tooltip.

Labels

Built-in text is English by default. Pass labels to Root to translate or reword the loading and empty messages, the data table, and the keyboard inspection controls. Every key of ChartLabels is optional; omitted keys keep their default.

<Chart.Root
    {data}
    {config}
    x="month"
    aria-label="Revenus mensuels"
    labels={{
        loading: 'Chargement…',
        empty: 'Aucune donnée',
        inspect: (category) => `Inspecter ${category}`
    }}
>
    <Chart.Plot>
        <Chart.Bar key="revenue" />
    </Chart.Plot>
</Chart.Root>

Mark and tick sizes

Line and Area take strokeWidth, the thickness of the line in pixels. Bar takes radius for the corner radius of each bar, 4 by default. Use 0 for square bars in a dense chart.

ticks on XAxis and YAxis is the number of ticks to aim for. Grid takes the same prop for its lines and defaults to 5.

API reference

Chart.Root

  • aria-label Required
    string

    Defines a string value that labels the current element.

  • labels
    ChartLabels

    Overrides the built-in text and accessible names. Every key is optional and English is the fallback.

  • data Required
    readonly T[]

    Rows to plot. Each row holds a category and one numeric field per series.

  • config Required
    { [x: string]: { label: string; color?: string | undefined; format?: ((value: number) => string) | undefined; }; }

    Label, color, and value format for each series, keyed by series.

  • x Required
    string

    Field of each row that holds its category.

  • orientation
    "vertical" | "horizontal"

    horizontal lays categories down the side and values across.

    Default 'vertical'

  • stacked
    boolean

    Stacks bars of the same category instead of placing them side by side.

    Default false

  • loading
    boolean

    Shows the loading state in place of the content.

    Default false

  • animation
    "reveal" | "live" | "none"

    reveal animates in once, live keeps a subtle motion running, and none is static.

    Default 'reveal'

  • children
    Snippet<[]>

    Content rendered inside.

Chart.Area

  • key Required
    string

    Series to draw. Matches a data field and a config entry.

  • class
    string

    Classes added to the element.

  • strokeWidth
    number

    Thickness of the line in pixels.

Chart.Bar

  • key Required
    string

    Series to draw. Matches a data field and a config entry.

  • class
    string

    Classes added to the element.

  • radius
    number

    Corner radius of each bar in pixels.

    Default 4

Chart.Grid

  • class
    string

    Classes added to the element.

  • ticks
    number

    Number of grid lines to aim for.

    Default 5

Chart.Legend

  • class
    string

    Classes added to the element.

  • children
    Snippet<[{ key: string; label: string; color: string; }]>

    Renders one legend entry. Omit it for a dot and the series label.

Chart.Line

  • key Required
    string

    Series to draw. Matches a data field and a config entry.

  • class
    string

    Classes added to the element.

  • strokeWidth
    number

    Thickness of the line in pixels.

Chart.Plot

  • children
    Snippet<[]>

    Marks, axes, and grid drawn inside the plot.

  • empty
    Snippet<[]>

    Replaces the built-in empty state.

  • loading
    Snippet<[]>

    Replaces the built-in loading skeleton.

Chart.Tooltip

  • class
    string

    Classes added to the element.

  • children
    Snippet<[{ label: string; values: { key: string; label: string; value: number; formatted: string; color: string; }[]; }]>

    Renders the tooltip body for the inspected category.

Chart.XAxis

  • class
    string

    Classes added to the element.

  • ticks
    number

    Number of ticks to aim for on a value axis.

  • format
    ((value: string | number) => string)

    Formats each tick label.

Chart.YAxis

  • class
    string

    Classes added to the element.

  • ticks
    number

    Number of ticks to aim for on a value axis.

  • format
    ((value: string | number) => string)

    Formats each tick label.