Chart

new

Charts on Unovis. A container that turns a config into series colours, a crosshair that reports the hovered point, a tooltip that is a real Vue component, and a legend that can hide a series.

Demo

Click a legend item to hide its series. The tooltip follows the pointer and a finger alike.

Chart is Unovis plus five parts. You compose the Unovis components yourself, VisXYContainer, VisArea, VisAxis, VisDonut and the rest, and the parts give them the theme's colours, a tooltip and a legend. The Area, Bar, Line and Tooltip galleries show the parts at work.

Installation

The item installs @unovis/vue and @unovis/ts.

Your first chart

Start from the data and a config. The config names each series, gives it a label and a colour, and the container writes every colour as --color-<key>:

<script setup lang="ts">
import { VisArea, VisAxis, VisXYContainer } from "@unovis/vue";

import { type ChartConfig, ChartContainer, ChartCrosshair, ChartLegend, ChartTooltip, ChartTooltipContent, chartColors } from "@/components/ui/chart";

type Month = { month: Date; desktop: number; mobile: number };

const data: Month[] = [
  { month: new Date(2024, 0, 1), desktop: 186, mobile: 80 },
  { month: new Date(2024, 1, 1), desktop: 305, mobile: 200 },
  { month: new Date(2024, 2, 1), desktop: 237, mobile: 120 },
];

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

const keys = ["desktop", "mobile"];
const x = (d: Month) => d.month;
const y = [(d: Month) => d.desktop, (d: Month) => d.mobile];
const color = chartColors(keys);
</script>

<template>
  <ChartContainer :config="config" class="aspect-auto h-64 w-full">
    <VisXYContainer :data="data">
      <VisArea :x="x" :y="y" :color="color" />
      <VisAxis type="x" :x="x" />
      <ChartCrosshair :x="x" :y-stacked="y" :color="color" />
    </VisXYContainer>
    <ChartTooltip>
      <ChartTooltipContent />
    </ChartTooltip>
    <ChartLegend />
  </ChartContainer>
</template>

Areas and stacked bars stack their series, so the crosshair takes y-stacked; lines, scatter and grouped bars take y. Left out, the crosshair reads them from the chart's components.

The container takes its width from its parent, never from what it draws, and is 16:9 by default. A chart with a fixed height takes aspect-auto as well, or the ratio turns that height into a minimum width.

Four rules keep a chart fast:

  • Accessors, formatters and svgDefs are constants in <script setup>. Unovis compares functions by identity, so an arrow written in the template is new on every render and redraws the whole chart with its 600ms transition.
  • Replace the data array; a mutation in place is not seen.
  • Dates are built with new Date(year, month, day). A "YYYY-MM-DD" string parses as UTC and lands a day early in western time zones.
  • Many charts on one page take lazy on the container: the slot mounts when it scrolls near.

Config

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

color is any CSS colour; the theme tokens var(--chart-1) to var(--chart-5) switch with the mode. A theme pair becomes light-dark(light, dark). A key must be a valid CSS identifier, so desktop, not desktop.total: the container warns in development.

chartColors(keys) returns an Unovis colour accessor that reads --color-<key> by series index, for the y arrays of areas, lines and bars. A single series writes the variable directly: :color="'var(--color-desktop)'".

Theming

The five series tokens ship with the tokens item, light and dark separately, in a fixed order that keeps every neighbouring pair apart under colour-vision deficiency. fill-chart-1 to fill-chart-5 and the bg- and stroke- forms exist as classes.

Unovis' own variables (--vis-axis-*, --vis-crosshair-*, --vis-donut-*, --vis-radial-bar-*) are mapped onto the tokens on the chart root: ticks in --muted-foreground, grid and domain lines in --border, donut and radial backgrounds in --muted, segments separated by a 2px --background stroke. Override one with a class on the container, [--vis-donut-segment-stroke-width:0].

Tooltip

ChartCrosshair listens to the pointer and reports the hovered point; ChartTooltip positions its content beside the pointer, inside the chart, and flips at the right edge. ChartTooltipContent lists the config keys found in the datum, in config order, with a zero shown as 0. Its props and slots are on the Tooltip gallery.

A chart the crosshair cannot follow, with no x axis or with bars on their side (a pie, a radial, a horizontal bar), feeds the tooltip from Unovis events. ChartContainer hands events to its slot: events(selector) returns the events object for the Unovis component whose marks carry that selector, Donut.selectors.segment or StackedBar.selectors.bar, and the same object every time, so it can sit in the template:

<script setup lang="ts">
import { Donut } from "@unovis/ts";
import { VisDonut, VisSingleContainer } from "@unovis/vue";

import { ChartContainer, ChartTooltip, ChartTooltipContent } from "@/components/ui/chart";
</script>

<template>
  <ChartContainer :config="config">
    <template #default="{ events }">
      <VisSingleContainer :data="data">
        <VisDonut :value="value" :color="color" :events="events(Donut.selectors.segment)" />
      </VisSingleContainer>
      <ChartTooltip>
        <ChartTooltipContent name-key="browser" hide-label />
      </ChartTooltip>
    </template>
  </ChartContainer>
</template>

A pointer and a finger both open the tooltip. A component rendered inside ChartContainer gets the same function from useChart(). Unovis binds events up to half a second after a render, so the first hover right after mount can be missed.

Legend

ChartLegend lists the config. With toggle every item is a button that hides its series; the keys arrive through v-model:hidden on the container, and useChartSeries(keys) turns them into y accessors that return null for a hidden series, so the remaining series keep their index and colour. Areas, lines and stacked bars draw nothing for it; grouped bars keep its slot empty, and want :bar-min-height="0" so no 2px stub remains:

<script setup lang="ts">
import { ref } from "vue";

import { useChartSeries } from "@/components/ui/chart";

const hidden = ref<string[]>([]);
const series = useChartSeries<Month>(["desktop", "mobile"], hidden);
</script>

<template>
  <ChartContainer :config="config" v-model:hidden="hidden">
    <VisXYContainer :data="data">
      <VisArea :x="x" :y="series.y.value" :color="series.color" />
    </VisXYContainer>
    <ChartLegend toggle />
  </ChartContainer>
</template>

Without the second argument the hook reads the hidden keys from the chart context, so it must run in a component rendered inside ChartContainer.

Accessibility

The SVG is hidden from assistive technology by Unovis. Give the container a label that says what the chart shows, and put the numbers beside it as a table, visually hidden if the design has no room, so the data is reachable without a pointer.

API Reference

Data attributes

data-slotAttributesDescription
chartdata-chart, role, aria-labelThe root; data-chart is the chart id, role="group" with aria-label when label is set.
chart-crosshair—Unovis' placeholder for the crosshair.
chart-tooltipdata-stateThe positioned box; data-state is open while a point is hovered.
chart-tooltip-content—The default content.
chart-tooltip-item—One row of the content.
chart-tooltip-indicator—The colour mark of a row.
chart-legend—The legend.
chart-legend-itemdata-state, aria-pressedOne series; data-state is visible or hidden, and with toggle the item is a button with aria-pressed.
chart-legend-swatch—The colour square.

CSS variables

VariableDefaultDescription
--chart-1 … --chart-5tokensThe series colours, per mode.
--color-<key>from the configSet on the chart root for every config key with a colour.
--vis-*mapped to the tokensUnovis' variables, set on the chart root; override on the container.

Changelog

  1. registry 0.24.0

    409c999 — Chart galleries: thirty examples in the Area, Bar and Line galleries, each a registry block ported from shadcn's charts.

    ChartContainer hands events to its default slot, so a chart the crosshair cannot follow (a pie, a horizontal bar) feeds the tooltip from Unovis events in its own template; events(selector) returns the same object for the same selector, so the chart does not re-render on every parent render.

    Fixes: a hovered area keeps its fill opacity instead of turning opaque; a root with no height keeps the chart's natural height instead of collapsing; the tooltip neither fades nor slides after the pointer under reduced motion.

  2. registry 0.23.0

    8f6aab4 — New Chart: charts on Unovis. ChartContainer turns a config into series colours (--color-<key>, light-dark() pairs) and maps Unovis' variables onto the theme; ChartCrosshair reports the hovered point with no trailing line; ChartTooltip and ChartTooltipContent are Vue components positioned beside the pointer, with slots, zero values shown and a finger supported; ChartLegend can hide a series. Five --chart-* tokens ship with the tokens item, light and dark, validated for colour-vision separation in both modes, so add @kappa-ui/chart brings them into a project set up before this release. The theme's :root now sets color-scheme: light.