<!-- Protocore Design System — ChartLegend -->
# ChartLegend

- **Category:** Charts (`charts`)
- **Slug:** `charts/chart-legend`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { ChartLegend } from "@protocore/pds/charts";`
- **Docs:** https://pds.protocore.io/components/charts/chart-legend

> A compact swatch-and-label legend row: 8px squares with mono-UPPERCASE muted labels.

## Import path

`ChartLegend` ships from the **`@protocore/pds/charts`** subpath. Unlike the chart wrappers it has **no recharts dependency** — it is a plain server-safe row — but it is grouped with the charts family on the subpath.

```tsx
import { ChartLegend } from "@protocore/pds/charts";
```

## When to use it

Use **ChartLegend** to name the series in any multi-series [LineChart](/charts/line-chart), [AreaChart](/charts/area-chart), or [BarChart](/charts/bar-chart) — essential because the monochrome ramp means readers cannot rely on hue alone to tell series apart. Place it in the container's `legend` slot for consistent alignment.

It is not the hover readout — that's [ChartTooltip](/charts/chart-tooltip), which shows per-point values. The legend is the persistent series key. For a single-series chart, skip it and let the [ChartContainer](/charts/chart-container) `label` carry the metric name.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `ChartLegendItem[]` | yes | — | Legend entries, in series order. `ChartLegendItem` = `{ label: ReactNode; color?: string }` — color defaults to `--pds-chart-N` by position. |
| `...rest` | `React.HTMLAttributes<HTMLDivElement>` | no | — | Spread onto the root `<div>` (e.g. `className`, `style`, `id`). |

## Examples

### Basics

Pass `items`, one per series in order. Each renders an 8px square swatch — defaulting to `--pds-chart-N` by position, matching how the wrappers color series — beside a mono-UPPERCASE muted label. Drop it into a [ChartContainer](/charts/chart-container)'s `legend` slot.

```tsx
import { ChartLegend } from "@protocore/pds/charts";

export default function Demo() {
  return (
    <ChartLegend
      items={[{ label: "eu-central-1" }, { label: "us-east-1" }, { label: "ap-south-1" }]}
    />
  );
}
```

### Custom swatch colors

Override `color` per item to map labels to specific ramp slots — e.g. green for healthy, amber for degraded — when your series order doesn't match the default `--pds-chart-N` sequence, or when the legend documents a semantic rather than positional encoding.

```tsx
import { ChartLegend } from "@protocore/pds/charts";

export default function Demo() {
  return (
    <ChartLegend
      items={[
        { label: "Healthy", color: "var(--pds-chart-4)" },
        { label: "Degraded", color: "var(--pds-chart-5)" },
        { label: "Baseline", color: "var(--pds-chart-2)" },
      ]}
    />
  );
}
```

## Do & don't

**Do**

- List items in the same order as the chart's `series` so swatch colors line up.
- Keep labels short — they render mono-UPPERCASE and truncation is ugly.
- Set `color` explicitly when the encoding is semantic (healthy/degraded), not positional.
- Place it in a ChartContainer `legend` slot for consistent spacing.

**Don't**

- Don't use it as a value readout — that's ChartTooltip's role.
- Don't add a legend to a single-series chart; the container label suffices.
- Don't invent swatch colors outside the `--pds-chart-*` ramp.
- Don't reorder items independently of the series — the swatches will lie.

## Accessibility

**Notes**

- Swatches are marked `aria-hidden`; the text label is the accessible content, so labels must be self-sufficient (color is a secondary cue, never the only one).
- The legend pairs with a monochrome ramp so series remain distinguishable in grayscale and for color-vision deficiencies.
- It is a static row with no interactive behavior; it does not toggle series visibility.

## Related

`chart-container`, `chart-tooltip`, `bar-chart`, `line-chart`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/