Legend

Legend displays a set of labeled color swatches, typically paired with a chart. Each item supports four swatch styles and an optional click handler for interactive series filtering.

  • Four swatch styles: rectangle, circle, line, dashed-line. Set a default with itemStyle and override per-item via item.style.
  • direction="vertical" stacks items in a column instead of wrapping them in a row.
  • Items with an onClick handler automatically receive role="button", tabIndex={0}, and respond to Enter / Space.
  • ariaLabel turns the container into a role="region" landmark for screen readers when the legend stands on its own.
  • All sub-elements (item, label, swatch) have a *ClassName escape hatch for fine-grained styling.

Import

import { Legend } from "h2o-library/charts";

Usage

Rectangle (default)

Appointments by month

Completed
Missed
Rescheduled
<Legend
  items={[
    { label: "Cardiology", color: "#4f46e5" },
    { label: "Neurology", color: "#06b6d4" },
    { label: "Pediatrics", color: "#10b981" },
  ]}
/>;

Circle Style

Best for pie/donut charts where the chart itself is composed of arcs.

Cases by specialty

Cardiology
Dermatology
Neurology
Urology
<Legend itemStyle="circle" items={items} />;

Line Style

Use line / dashed-line swatches when paired with a LineChart so the legend shape matches the chart shape.

Case stats

Actual
Forecast
<Legend itemStyle="line" items={items} />;

Vertical Layout

Stack items in a column instead of a row — useful when the legend sits next to a narrow chart.

<Legend direction="vertical" items={items} />;

Per-Item Style Override

Mix swatch styles across items by setting style on individual items — handy for forecast/actual line charts where one series should appear dashed.

<Legend
  itemStyle="line"
  items={[
    { label: "Actual", color: "#041957" },
    { label: "Forecast", color: "#3767F6", style: "dashed-line" },
  ]}
/>;

Click Handler

Clickable items are keyboard-activatable and visually distinct on hover.

Appointments by month (Clickable)

Completed
Missed
Rescheduled
<Legend
  items={items.map((item) => ({
    ...item,
    onClick: () => toggleSeries(item.label),
  }))}
/>;

ARIA Landmark

Pass ariaLabel when the legend stands on its own — the container becomes a role="region" with the label.

<Legend ariaLabel="Chart legend" items={items} />;

Playground

Loading playground…

Keyboard

When an item defines onClick, that row becomes role="button" with tabIndex={0}. Use Tab to focus and Enter or Space to trigger the handler.

Props

Legend

PropTypeDefaultDescription
items*LegendItem[]—Array of legend entries. Each item has label, color, optional onClick, and optional per-item style override.
itemStyle"rectangle" | "circle" | "line" | "dashed-line""rectangle"Default swatch shape for all items. Individual items can override this with their own style.
direction"horizontal" | "vertical""horizontal"Layout direction — horizontal wraps items in a row, vertical stacks them in a column.
ariaLabelstringundefinedAccessible label for the legend container. When provided, the container receives role="region".
classNamestringundefinedAdditional class for the outer container.
itemClassNamestringundefinedAdditional class applied to each legend item.
labelClassNamestringundefinedAdditional class applied to each item label.
colorClassNamestringundefinedAdditional class applied to each color swatch.

* Required

LegendItem

PropTypeDefaultDescription
label*string—Display text for this legend entry.
color*string—CSS color value for the swatch (hex, rgb, hsl, etc.).
onClick() => voidundefinedClick handler that makes the item interactive (cursor pointer, hover state, keyboard activation).
style"rectangle" | "circle" | "line" | "dashed-line"itemStylePer-item swatch style override.

* Required

Design Guidelines

  • Place the legend near the chart it describes, typically below or to the right.
  • Match the swatch style to the chart shape: circle for PieChart, line / dashed-line for LineChart, rectangle for BarChart and most everything else.
  • Use direction="vertical" when paired with a narrow chart or when horizontal space is limited.
  • Reach for onClick when users should be able to toggle individual data series.
  • For polished cards with a built-in legend, use the Chart wrapper — it derives the legend from the data.

Accessibility

  • Clickable legend items automatically receive role="button" and tabIndex={0}.
  • Keyboard users can activate clickable items with Enter or Space.
  • Provide ariaLabel when the legend is a standalone navigable region on the page.