# Chart (/docs/charts/building-blocks/chart)

Every family root, like `LineChart` or `BarChart`, takes the same options for its data, series config, accessible name, size, legend behavior and HTML frame. This page covers those; each [chart page](../components/line.mdx) covers the options its family adds.

<Example caption="Delivery starts highlighted. Press Pickup or Delivery in the legend to move the highlight, or press it again to clear it.">
<Basic />

```tsx
"use client";

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

const data = [
  { day: "Mon", pickup: 24, delivery: 41 },
  { day: "Tue", pickup: 30, delivery: 38 },
  { day: "Wed", pickup: 27, delivery: 45 },
  { day: "Thu", pickup: 35, delivery: 52 },
  { day: "Fri", pickup: 42, delivery: 61 },
];

const config = {
  pickup: { label: "Pickup", color: "#0f8b8d" },
  delivery: { label: "Delivery", color: "#733bff" },
} satisfies SeriesConfig;

export default function OrdersChart() {
  return (
    <BarChart
      data={data}
      config={config}
      height={240}
      interaction={{
        kind: "series",
        eligibleKeys: Object.keys(config),
        defaultSelected: "delivery",
      }}
      legendPosition="top"
      aria-label="Daily orders by fulfillment"
    >
      <BarChart.Grid />
      <BarChart.XAxis dataKey="day" />
      <BarChart.YAxis width={32} />
      <BarChart.Series dataKey="pickup" />
      <BarChart.Series dataKey="delivery" />
      <BarChart.Tooltip />
      <BarChart.Legend />
    </BarChart>
  );
}
```
</Example>

## Usage [#usage]

### Name and Parts [#name-and-parts]

Pass `config`, then `aria-label` or `aria-labelledby`. The chart throws without them, so a chart can't ship without a name. It draws only the parts you add as children, like axes, series, tooltip and legend; pass `children={null}` for an empty frame on purpose. Families don't nest: put each chart in its own root.

### Size [#size]

A chart fills its container's width and is 280px tall (activity rings are 300px). Set `height`, `width`, `style` or `className` to change it; your values win over the defaults. A percentage height needs a parent with a measured height. Set `responsive={false}` to size the chart with fixed `width` and `height` only.

`className`, `style`, refs and handlers go to the plot. To reach the outer HTML frame that also holds the legend, pass them in `frameProps`. `legendPosition` puts the legend and other HTML parts `"bottom"` (the default) or `"top"`.

### Highlight [#highlight]

Pressing a legend item highlights its series and dims the rest; pressing it again, or pressing Escape, clears it. Screen readers hear "Highlighted Delivery." and "Highlight cleared." Pressing a bar, slice or point does the same in families whose marks support it; set `interaction.markActivation` to `"none"` to limit it to the legend.

Set `interaction` to own the highlight. `defaultSelected` starts with one highlighted, as in the example; `selected` with `onSelectionChange` puts it in your state. `eligibleKeys` lists the keys the legend acts on, so include hidden and zero-valued series:

```tsx
const [selected, setSelected] = useState<string | null>(null);

<BarChart
  interaction={{
    kind: "series",
    eligibleKeys: ["pickup", "delivery"],
    selected,
    onSelectionChange: setSelected,
  }}
  {...props}
/>
```

`kind` is `"series"` for series, `"category"` for categories like pie slices, and `"node"` for Sankey nodes. To cancel an action, return `false` from `interaction.onBeforeInteraction`, or call `event.preventDefault()` in an `onClick` you pass to the legend; it runs first.

### Hide and Show [#hide-and-show]

Set `interaction.mode` to `"visibility"` and the legend hides and shows series instead. Pass `defaultVisibleSeries` to let the chart own the list, or `visibleSeries` with `onVisibleSeriesChange` to own it yourself. The [Legend](./legend.mdx) page shows it in action.

Pass one of `visibleSeries` or `defaultVisibleSeries`, not both. `onVisibleSeriesChange` needs one of them; `visibleSeries` without it is read-only. The legend always keeps one series visible, but your own state can hide them all, so show an empty message when it does.

### Emphasis [#emphasis]

Hovering or focusing a series, in the legend or on the plot, dims the others while the pointer or focus stays. Set `emphasis="none"` to turn it off. Bar charts also take `emphasis="category"` to dim the other categories while one is hovered.

### Content [#content]

Add `.Content` for HTML next to the plot, like a control or a status line. It renders in the same frame as the legend, keeps the chart's context and hides while the chart is loading:

```tsx
<LineChart.Content>
  <button type="button" onClick={refresh}>Refresh</button>
</LineChart.Content>
```

### Loading [#loading]

Set `loading` while the data is on its way. The chart keeps its size and shows a placeholder in its own shape, the legend and other HTML parts hide, and screen readers hear `loadingLabel` ("Loading chart" by default). Highlight and visibility carry over when `loading` turns off. Show your own message for errors and empty results.

### Colors in CSS [#colors-in-css]

Each config key `revenue` sets a `--color-revenue` CSS variable on the frame, so custom marks and HTML can match the series. See [Series Config](./series-config.mdx).

## API Reference [#api-reference]

### Chart Root [#chart-root]

### ChartRootOptions

| Prop                     | Type                                                                                                                                                                                                                                     | Description                                                                                     |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `visibleSeries?`         | `readonly string[] \| undefined`                                                                                                                                                                                                         | The series keys to show, when you control visibility.                                           |
| `defaultVisibleSeries?`  | `readonly string[] \| undefined`                                                                                                                                                                                                         | The series keys to show first, when the chart controls visibility.                              |
| `onVisibleSeriesChange?` | `((next: string[]) => void) \| ((next: string[]) => void) \| undefined`                                                                                                                                                                  | Called with the next visible series keys when the legend hides or shows one.                    |
| `config`                 | `Readonly<Record<string, { label?: string; color: SeriesColor; pattern?: FillPattern; icon?: ComponentType; legendShape?: NonNullable<React.ComponentProps<typeof Symbols>["type"]>; formatValue?: (value: ValueType) => ReactNode; }>>` | The label, color and value format of each series, keyed by its `dataKey` or `seriesKey`.        |
| `emphasis?`              | `"auto" \| "none"`                                                                                                                                                                                                                       | Dims the other series while one is hovered or focused. `"none"` turns it off. Default: `"auto"` |
| `interaction?`           | `ChartInteractionConfig \| undefined`                                                                                                                                                                                                    | What pressing a legend item does: highlight a series (the default) or hide and show it.         |
| `legendPosition?`        | `"bottom" \| "top"`                                                                                                                                                                                                                      | Places the legend and other HTML parts above or below the plot. Default: `"bottom"`             |
| `frameProps?`            | `` (Omit<ChartProviderProps, "children" \| "config" \| "defaultVisibleSeries" \| "emphasis" \| "interaction" \| "nonce" \| "onVisibleSeriesChange" \| "visibleSeries"> & { [key: `data-${string}`]: unknown; }) \| undefined ``          | Attributes, handlers and ref for the outer HTML frame. Plot props remain on the chart.          |

### interaction [#interaction]

### ChartInteractionOptions

| Prop                   | Type                                                                                | Description                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `markActivation?`      | `"matching-legend" \| "none"`                                                       | Whether pressing a mark acts like pressing its legend item. `"none"` limits it to the legend. Focus mode defaults to `"matching-legend"`. |
| `eligibleKeys`         | `readonly string[]`                                                                 | The keys the legend can act on, including hidden and zero-valued ones.                                                                    |
| `onBeforeInteraction?` | `((request: ChartInteractionRequest) => boolean \| void) \| undefined`              | Called before each legend or mark action. Return `false`, or call `event.preventDefault()`, to cancel it.                                 |
| `kind`                 | `"category" \| "node" \| "series"`                                                  | What the legend items stand for: series, categories (like pie slices) or Sankey nodes.                                                    |
| `mode?`                | `"focus" \| "visibility"`                                                           | `"focus"` highlights the pressed item and dims the rest. `"visibility"` hides and shows it. Default: `"focus"`                            |
| `selected?`            | `string \| null \| undefined`                                                       | The highlighted key, or `null`, when you own the highlight. Pass `onSelectionChange` with it.                                             |
| `defaultSelected?`     | `string \| null \| undefined`                                                       | The key highlighted first, when the chart owns the highlight.                                                                             |
| `onSelectionChange?`   | `((next: string \| null) => void) \| ((next: string \| null) => void) \| undefined` | Called with the newly highlighted key, or `null` when the highlight clears.                                                               |