Identity
Tie each value to a stable key so labels, colors and state follow it.
A value says how much; its identity says which series or category it belongs to. Charts use that identity, a key in Series Config, to find a label and color, and to track what's highlighted or hidden. Keep keys stable when you sort, filter or reload data, and keep them separate from display text, which can change with the locale.
Series
A series' dataKey reads its value from each row, and when it's a string, it's also the config key. When the series reads its value with a function, or the row field isn't the name you want as its identity, set seriesKey to the config key:
const config = {
visitors: { label: "Visitors", color: "#733bff" },
} satisfies SeriesConfig;
<LineChart data={data} config={config} aria-label="Monthly visitors">
<LineChart.XAxis dataKey="month" />
<LineChart.Series<Row> dataKey={(row) => row.count} seriesKey="visitors" />
<LineChart.Legend />
</LineChart>The line reads count from each row, but its label, color, legend item and visibility all use visitors. Without seriesKey, the chart can't match the series to its config.
Categories and Nodes
Some charts color each item instead of each series. Give every item an ID that matches a config key, and its color stays with it however the rows are sorted:
| Chart | Identity |
|---|---|
| Pie | PieChart.Series reads each slice's ID from categoryKey |
| Radial | RadialBarChart reads each bar's ID from categoryKey; each activity ring's key matches its config |
| Sankey | Each node's ID matches its config |
| Heatmap | Row and column IDs place each cell; a color scale colors its value |
const data = [
{ id: "search", visitors: 35 },
{ id: "direct", visitors: 65 },
];
const config = {
search: { label: "Search", color: "#733bff" },
direct: { label: "Direct", color: "#0f8b8d" },
} satisfies SeriesConfig;
<PieChart config={config} aria-label="Visitors by source">
<PieChart.Series data={data} dataKey="visitors" categoryKey="id" />
<PieChart.Legend />
</PieChart>To let the legend highlight or hide categories, set interaction.kind to "category" (or "node" for Sankey) with those IDs as eligibleKeys. See Chart.
Keys in State
visibleSeries, selected and eligibleKeys all hold config keys, never labels or row positions. Include keys whose value is zero or that are hidden right now in eligibleKeys, so the legend can still bring them back.