# Legend (/docs/charts/building-blocks/legend)

Use `.Legend` to name the series a chart draws, with a marker in each one's color. Every family that draws series from `config` has one, like `LineChart.Legend` or `PieChart.Legend`. It renders as an HTML list next to the plot, and its labels and colors come from [Series Config](./series-config.mdx).

<Example caption="Press a platform in the legend to hide its line, and press it again to bring it back.">
<Basic />

```tsx
"use client";

import { LineChart, type SeriesConfig } from "@kind-ui/charts";

const data = [
  { month: "Jan", web: 420, ios: 310, android: 260 },
  { month: "Feb", web: 470, ios: 340, android: 300 },
  { month: "Mar", web: 450, ios: 390, android: 330 },
  { month: "Apr", web: 530, ios: 420, android: 380 },
  { month: "May", web: 580, ios: 470, android: 400 },
  { month: "Jun", web: 640, ios: 510, android: 450 },
];

const config = {
  web: { label: "Web", color: "#733bff" },
  ios: { label: "iOS", color: "#0f8b8d" },
  android: { label: "Android", color: "#e07a2f" },
} satisfies SeriesConfig;

export default function SignupsChart() {
  return (
    <LineChart
      data={data}
      config={config}
      interaction={{ kind: "series", mode: "visibility", eligibleKeys: Object.keys(config) }}
      defaultVisibleSeries={["web", "ios", "android"]}
      margin={{ right: 16 }}
      aria-label="Monthly sign-ups by platform"
    >
      <LineChart.Grid />
      <LineChart.XAxis dataKey="month" />
      <LineChart.YAxis width={40} />
      <LineChart.Series dataKey="web" />
      <LineChart.Series dataKey="ios" />
      <LineChart.Series dataKey="android" />
      <LineChart.Tooltip />
      <LineChart.Legend />
    </LineChart>
  );
}
```
</Example>

## Usage [#usage]

### Highlight or Hide [#highlight-or-hide]

By default each legend item is a button that highlights its series and dims the rest, without changing the data. Press it again, or press Escape, to clear the highlight.

To hide and show series instead, set `interaction` to `"visibility"` mode on the chart and give it `defaultVisibleSeries`, as in the example, or `visibleSeries` with `onVisibleSeriesChange` to keep the list in your state. Hiding a series keeps the axes and the other series where they were. The legend won't hide the last visible series. The [Chart](./chart.mdx) page covers both modes and their state.

### Keyboard and Screen Readers [#keyboard-and-screen-readers]

Each item is a button, so Tab reaches it and Enter or Space presses it. It's `aria-pressed` while its series is highlighted, or visible in visibility mode, and screen readers hear what changed: "Highlighted Web.", "Highlight cleared.", "Hidden iOS." or "Shown iOS." When pressing would hide the last series, they hear "At least one item must remain visible." The list is named "Chart legend"; pass `aria-label` to change it.

Hovering or focusing an item dims the other series while it lasts. Set `emphasis="none"` on the legend to turn that off.

### Markers [#markers]

Each item shows a small swatch in its series' color. A series config `icon`, `legendShape` or `pattern` replaces it with that icon, symbol or pattern. Pass `hideIcon` to show swatches for every item.

### Item Content [#item-content]

Pass a function as children to render each item's content yourself. It gets the item's `key`, `label`, `marker`, `visible`, `selected` and the legend's `mode`. The legend still owns the button, so keep the content noninteractive:

```tsx
<LineChart.Legend>
  {({ marker, label, visible }) => (
    <>
      {marker}
      {label}
      {visible ? null : " (hidden)"}
    </>
  )}
</LineChart.Legend>
```

### Placement [#placement]

The legend sits below the plot. Set `legendPosition="top"` on the chart to move it, and every other HTML part, above the plot. While the chart is `loading`, the legend hides.

## API Reference [#api-reference]

### LegendOptions

| Prop        | Type                                                                                                                                                         | Description                                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `hideIcon?` | `boolean \| undefined`                                                                                                                                       | Shows a color swatch for every item, ignoring each series' `icon`, `legendShape` and `pattern`. Default: `false`                    |
| `emphasis?` | `"none" \| "series"`                                                                                                                                         | Dims the other series while an item is hovered or focused. `"none"` turns it off; pressing an item still works. Default: `"series"` |
| `children?` | `((item: { key: string; label: string; visible: boolean; selected: boolean; mode: "visibility" \| "focus"; marker: ReactNode; }) => ReactNode) \| undefined` | Renders each item's content inside its button. Keep it noninteractive; the legend owns the button and its state.                    |

<Caption>
Heatmaps show a color scale with `HeatmapChart.Legend`, and Sankey charts list their nodes with `SankeyChart.Legend`. See [Heatmap](../components/heatmap.mdx) and [Sankey](../components/sankey.mdx).
</Caption>