Legend

ImportCopy Anchor Link

import { Legend } from '@nizivo/charts/legend';

Static or interactiveCopy Anchor Link

Server. Legend has no 'use client' and imports no client module. It is a list, not a control: a series toggle would be a later, additive change. How to choose.

Pass it to a ChartFrame as legend; the frame renders it between the caption and the plot in every status. AreaChart builds its own when it has a comparison series, and DonutChart always does.

ExamplesCopy Anchor Link

BasicCopy Anchor Link

import type { JSX } from 'react';
import { Legend } from '@nizivo/charts/legend';

export function LegendExample(): JSX.Element {
  return (
    <Legend
      items={[
        { label: 'This period', series: 'current' },
        { label: 'Previous', series: 'previous' },
      ]}
    />
  );
}

VerticalCopy Anchor Link

import type { JSX } from 'react';
import { Legend } from '@nizivo/charts/legend';

export function LegendVerticalExample(): JSX.Element {
  return (
    <Legend
      orientation="vertical"
      items={[
        { label: 'Online store', series: 'cat-1', value: '$64,120', share: '52%' },
        { label: 'Retail', series: 'cat-2', value: '$33,410', share: '27%' },
        { label: 'Wholesale', series: 'cat-3', value: '$17,260', share: '14%' },
        { label: 'Other', series: 'other', value: '$8,630', share: '7%' },
      ]}
    />
  );
}

PropsCopy Anchor Link

Server component. Props: LegendProps. Source: src/legend/legend.tsx.

• Also takes every <ul> attribute except children.

render takes an element, or, in client code, a function of the props and this state (LegendState):

items holds one LegendItem per series or category (its fields are under Other exports): series is the colour role, shared with the chart's marks ('current' | 'previous' | 'cat-1' | 'cat-2' | 'cat-3' | 'other'); value and share are pre-formatted (Numeric/M, and Mono/M tertiary, for example "52%"). orientation="horizontal" wraps in a row (line charts); vertical is the donut's table-like list.

Other exportsCopy Anchor Link

ChartSeries type

import type { ChartSeries } from '@nizivo/charts/legend'

The colour role of a series, shared by its marks and its legend swatch as data-series (contracts/vocabulary.json). current is chart/primary; previous the dashed chart/neutral comparison (decorative: the data table carries its values); cat-1…cat-3 the categorical colours, which never cycle; other the folded remainder (chart/neutral).

type ChartSeries = "current" | "previous" | "cat-1" | "cat-2" | "cat-3" | "other"

LegendItem type

import type { LegendItem } from '@nizivo/charts/legend'

Name	Type	Default	Description
id	string	–	Stable key; the label when absent.
labelrequired	string	–
seriesrequired	ChartSeries "current" | "previous" | "cat-1" | "cat-2" | "cat-3" | "other"	–
share	string	–	A pre-formatted share, for example "52%" (Mono/M, tertiary).
value	string	–	A pre-formatted value (the donut legend's Numeric/M column).

LegendProps type

import type { LegendProps } from '@nizivo/charts/legend'

The props of Legend, listed above.

LegendState type

import type { LegendState } from '@nizivo/charts/legend'

The render state of Legend, listed above.

Data attributes and slotsCopy Anchor Link

The mark's colour follows data-series: current in chart/primary, previous in chart/neutral, cat-1 to cat-3 in chart/cat-1 to chart/cat-3, other in chart/neutral.

AccessibilityCopy Anchor Link

• A plain list: each item's text is its label, then its value and share when given. The mark is aria-hidden, so the name, not the colour, identifies the series.
• Forced colours: the marks take system colours that match the marks they name: the current series CanvasText, the comparison GrayText (still dashed), and categories as DonutChart's segments (Highlight, hollow Canvas, CanvasText, GrayText, each outlined in CanvasText). Only Chromium's forced-colours emulation has been looked at; the treatment awaits an accessibility review.

FigmaCopy Anchor Link

Chart Legend Item, 7275:13291: Mark=Line 7275:13292 (92 × 21), Mark=Dashed 7275:13296 (92 × 21) and Mark=Dot 7275:13300 (86 × 21). Figma's donut legend is a custom row with a 10 px dot, not this component; code draws both from Legend. Notes: docs/figma/03-data-viz.md §4.1.