# Series Config (/docs/charts/building-blocks/series-config)

Use a `SeriesConfig` to name and color the series a chart draws. Every family takes one as `config`, and the legend, tooltip and marks all read from it, so a series looks and reads the same everywhere.

<Example caption="Switch the site between light and dark to see each series change color. Hover a week to see its values in terabytes.">
<Basic />

```tsx
"use client";

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

const data = [
  { week: "W1", storage: 1.2, transfer: 0.6 },
  { week: "W2", storage: 1.4, transfer: 0.9 },
  { week: "W3", storage: 1.5, transfer: 0.8 },
  { week: "W4", storage: 1.9, transfer: 1.1 },
  { week: "W5", storage: 2.1, transfer: 1.4 },
  { week: "W6", storage: 2.4, transfer: 1.3 },
];

const terabytes = (value: unknown) => `${value} TB`;

const config = {
  storage: {
    color: { light: ["#3659b8", "#7c9cf0"], dark: ["#93b4ff", "#c7d6ff"] },
    formatValue: terabytes,
  },
  transfer: {
    label: "Data transfer",
    color: { light: "#b45309", dark: "#fbbf24" },
    formatValue: terabytes,
  },
} satisfies SeriesConfig;

export default function UsageChart() {
  return (
    <AreaChart
      data={data}
      config={config}
      margin={{ right: 16 }}
      aria-label="Weekly usage, in terabytes"
    >
      <AreaChart.Grid />
      <AreaChart.XAxis dataKey="week" />
      <AreaChart.YAxis width={40} />
      <AreaChart.Series dataKey="storage" type="monotone" />
      <AreaChart.Series dataKey="transfer" type="monotone" />
      <AreaChart.Tooltip />
      <AreaChart.Legend />
    </AreaChart>
  );
}
```
</Example>

## Usage [#usage]

### Keys [#keys]

Each key is the series' identity. A series whose `dataKey` is `"storage"` reads the `storage` entry; a series that reads its value with a function names its entry with `seriesKey`. For pie slices, radial bars and Sankey nodes, the key matches the category or node ID instead. See [Identity](../guides/identity.mdx).

Keys start with a letter and contain only letters, numbers, underscores and hyphens. The legend lists the entries in config order.

### Labels [#labels]

`label` is the name the legend and tooltip show. Omit it and the chart derives one from the key: `storage` becomes "Storage" and `monthlyVisitors` becomes "Monthly visitors".

### Colors [#colors]

`color` takes any CSS color, including a CSS variable. Pass an array for gradient stops, spaced evenly along the series, or `{ light, dark }` for one color or gradient per color scheme. The chart picks one with the CSS `light-dark()` function, so set `color-scheme` on the page (or the chart's container) to match your theme.

```tsx
const config = {
  revenue: { label: "Revenue", color: "var(--chart-1)" },
  forecast: { label: "Forecast", color: { light: "#3659b8", dark: "#93b4ff" } },
} satisfies SeriesConfig;
```

Each key also sets a `--color-<key>` CSS variable on the chart, the first stop for a gradient, so your own marks and HTML can match. A `fill` or `stroke` you pass to a series, or a `Cell`, wins over the config color.

### Value Format [#value-format]

`formatValue` turns a value into what the tooltip shows, like `"2.4 TB"`. A `formatter` you pass to the tooltip wins over it.

### Markers [#markers]

Use `icon` to show a component, like an SVG icon, in place of the color marker in the legend and tooltip. Use `legendShape` for a symbol like `"triangle"` in the legend, matching a scatter series' `shape`. Use `pattern` to fill bars and areas with a pattern, which the legend swatch shows too:

```tsx
const config = {
  planned: { label: "Planned", color: "#64748b", pattern: { kind: "hatch" } },
} satisfies SeriesConfig;
```

`pattern.kind` is `hatch`, `stripe`, `duotone`, `dots` or `lines`. Patterns, shapes and icons give readers a second cue besides color.

## API Reference [#api-reference]

### SeriesConfigEntry

| Prop           | Type                                                                            | Description                                                                                                             |
| -------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `label?`       | `string \| undefined`                                                           | The name the legend and tooltip show. Omit it to derive one from the key: `monthlyVisitors` becomes "Monthly visitors". |
| `color`        | `SeriesColor`                                                                   | A CSS color, an array of gradient stops, or `{ light, dark }` with one of either per color scheme.                      |
| `pattern?`     | `FillPattern \| undefined`                                                      | A fill pattern for bars and areas, also drawn in the legend swatch.                                                     |
| `icon?`        | `ComponentType \| undefined`                                                    | A decorative icon shown in place of the color marker in the legend and tooltip.                                         |
| `legendShape?` | `"circle" \| "cross" \| "diamond" \| "square" \| "star" \| "triangle" \| "wye"` | The legend marker's symbol, like `"circle"` or `"triangle"`. Match it to a scatter series' `shape`.                     |
| `formatValue?` | `((value: TooltipValueType) => ReactNode) \| undefined`                         | Formats this series' values in the tooltip.                                                                             |