Legend
legendExplains chart series or status colors with compact labeled markers.
Usage
Basic usage
Color point + series name, the default colors are chart-1..6 in order, which is the same set of token as Chart.
- Opened
- Closed
- Merged
<Legend items={[{ label: "Opened" }, { label: "Closed" }, { label: "Merged" }]} />With self-drawn graphics
Legend of recharts cannot appear outside the picture - self-drawn Sparkline / Heatmap / Use this for the legend of the contribution wall.
- This week1.2k
- Last week980
<div className="flex items-center justify-between">
<Legend
marker="line"
items={[
{ label: "This week", color: "primary", value: "1.2k" },
{ label: "Last week", color: "muted", value: "980" },
]}
/>
<Sparkline data={[3, 7, 4, 9, 6, 11, 8]} variant="bar" />
</div>Vertical arrangement · With numerical value
layout="column" When value is automatically right-aligned, it fits the series table next to the pie chart.
- Natural traffic48%
- Paid placement31%
- Private domain repurchase21%
<Legend
layout="column"
marker="square"
items={[
{ label: "Natural traffic", value: "48%" },
{ label: "Paid placement", value: "31%" },
{ label: "Private domain repurchase", value: "21%" },
]}
/>Click to switch series
After passing onItemClick, the entry becomes a button (aria-pressed expression switch); the visibility is controlled, and the state is held by the caller.
const [hidden, setHidden] = useState<Record<string, boolean>>({ merged: true })
<Legend
items={series.map((i) => ({ ...i, hidden: hidden[i.id] }))}
onItemClick={(item) => setHidden((h) => ({ ...h, [item.id]: !h[item.id] }))}
/>When to use
Use Legend beside custom visuals such as Sparkline, Heatmap, ContributionGraph, WorldMap, Funnel, or small card graphics.
Recharts legends only exist inside a chart, and Chart already includes one. This component standardizes out-of-chart marker shapes and defaults to the same chart-1..6 token sequence.
Import
import { Legend, type LegendItem } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| items* | LegendItem[] | — | { label, color?, value?, hidden?, id? }[]. |
| marker | "dot" | "square" | "line" | "dot" | Marker shape. |
| layout | "row" | "column" | "row" | Wrapping row or vertical column with right-aligned values. |
| size | "sm" | "md" | "md" | Component size. |
| onItemClick | (item, index) => void | — | Makes each item a button when supplied. |
| className | string | — | Custom class and forwarded native attributes. |
LegendItem
| Field | Type | Description |
|---|---|---|
| label* | ReactNode | Series name. |
| color | string | Semantic name or CSS color; omission uses chart tokens by index. |
| value | ReactNode | Value or percentage after the label. |
| hidden | boolean | Mutes a disabled series without removing its toggle. |
| id | string | number | Stable identity returned by the click callback. |
Pitfalls
- Visibility is controlled by the caller so the legend and graphic share one source of truth.
- Keep hidden items present and muted, or users cannot toggle them back on.
- Do not duplicate the built-in Recharts legend inside Chart.
Related
Chart · Sparkline · ContributionGraph · Heatmap · Stat
Playground
- Opened42
- Closed
- Merged
<Legend
items={[{ label: "Opened" }, { label: "Closed" }]}
/>