# Chart

> A bar, line or area chart that gives one reading at a time and one thing to take from it.

```tsx
'use client';

import { useState } from 'react';
import { Button, Chart, Switch } from '@brand-studio/ui';

const week = { labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'], hot: [42, 38, 45, 51, 58, 74, 61], iced: [12, 15, 14, 22, 31, 48, 39] };
const month = {
  labels: Array.from({ length: 30 }, (_, day) => day < 17 ? `${14 + day} Sep` : `${day - 16} Oct`),
  hot: [44, 39, 41, 47, 55, 71, 60, 43, 40, 46, 49, 57, 76, 63, 45, 41, 44, 52, 59, 78, 66, 42, 38, 45, 51, 58, 74, 61, 47, 43],
  iced: [28, 26, 25, 27, 34, 52, 44, 24, 22, 23, 25, 30, 47, 40, 20, 18, 19, 22, 27, 41, 35, 14, 15, 14, 22, 31, 48, 39, 16, 13],
};
const cups = (value: number) => `${value} cups`;

export default function ChartDemo() {
  const [long, setLong] = useState(false);
  const [iced, setIced] = useState(false);
  const data = long ? month : week;
  const series = [{ name: 'Hot', values: data.hot }, ...(iced ? [{ name: 'Iced', values: data.iced }] : [])];
  return (
    <div style={{ width: '100%', maxWidth: 620, display: 'grid', gap: 16 }}>
      <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', justifyContent: 'space-between', gap: 12 }}>
        <div role="group" aria-label="Period" style={{ display: 'flex', gap: 8 }}>
          <Button tone={long ? 'secondary' : 'primary'} aria-pressed={!long} onClick={() => setLong(false)}>This week</Button>
          <Button tone={long ? 'primary' : 'secondary'} aria-pressed={long} onClick={() => setLong(true)}>30 days</Button>
        </div>
        <Switch label="Compare iced" checked={iced} onCheckedChange={setIced} />
      </div>
      <Chart
        title="Cups sold"
        kind={long ? 'area' : 'bar'}
        labels={data.labels}
        series={series}
        lit={iced || long ? 'Hot' : 'Sat'}
        note={long ? 'Saturdays peak every week. Iced drinks fade as October cools.' : iced ? 'Iced drinks sell most at the weekend.' : 'Saturday was the busiest day: 74 cups.'}
        format={cups}
      />
    </div>
  );
}
```

## Installation

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, Chart } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { Chart } from '@brand-studio/ui';
```

```tsx
<Chart
  title="Cups sold"
  labels={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']}
  series={[{ name: 'Hot', values: [42, 38, 45, 51, 58, 74, 61] }]}
  lit="Sat"
  note="Saturday was the busiest day: 74 cups."
  format={value => `${value} cups`}
/>
```

Set `kind` to `bar`, `line` or `area`. Bars and areas are measured from zero, so zero is always on their axis; a line's axis fits its values. A `null` value leaves a gap.

## One accent

A brand has one accent, so a chart has one lit thing. `lit` names the series to draw in the accent. With a single series it can name a label, and that point alone takes the accent while the rest step back. Other series are drawn in ink, then in a quiet tone with a dashed line. Three series is the most that reads clearly; past that, use a [Data Table](/docs/components/data-table/).

## Note and reading

`note` is the one thing to take from the chart, in a sentence. It shows until someone points at the chart, drags across it or moves through it with the arrow keys; then the same line shows that point's values. The line keeps its height, so the chart never jumps.

## Size

The chart fills the width it is given and thins its bottom labels when there is no room for all of them. Set `--bs-chart-height` to change the height of the plot.

## Accessibility

- Every value is also in a table that screen readers reach. The drawing itself is hidden from them.
- The plot takes focus. Left and right arrows move one point, Home and End jump to the ends, and Escape clears the reading.
- A fill never carries meaning by colour alone: each tone has its own edge, the quiet line is dashed, and the reading names each series.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `title` | `string` | – |
| `labels` | `string[]` | – |
| `series` | `ChartSeries[]` | – |
| `kind?` | `"area" \| "bar" \| "line"` | `'bar'` |
| `lit?` | `string` | – |
| `note?` | `React.ReactNode` | – |
| `format?` | `((value: number) => string)` | – |
| `empty?` | `React.ReactNode` | `'Nothing to chart yet.'` |
| `noValueLabel?` | `string` | `'No value'` |
| `keysLabel?` | `string` | `'Use the arrow keys to read each point'` |
| `hideTitle?` | `boolean` | `false` |
| `className?` | `string` | `''` |

Source: https://brandstudio.js.org/docs/components/chart/
