# Line Chart (/docs/charts/components/line)

Use a line chart to show how a measure changes across ordered categories, like months or days, and to compare a few measures on the same scale.

<Example caption="Hover a point, or focus the chart and press the arrow keys, to see its value.">
<Basic />

```tsx
"use client";

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

const data = [
  { month: "Jan", visitors: 420 },
  { month: "Feb", visitors: 580 },
  { month: "Mar", visitors: 510 },
  { month: "Apr", visitors: 760 },
  { month: "May", visitors: 680 },
  { month: "Jun", visitors: 910 },
  { month: "Jul", visitors: 840 },
  { month: "Aug", visitors: 1070 },
  { month: "Sep", visitors: 960 },
  { month: "Oct", visitors: 1180 },
  { month: "Nov", visitors: 1110 },
  { month: "Dec", visitors: 1360 },
];

const config = {
  visitors: { label: "Visitors", color: "#733bff" },
} satisfies SeriesConfig;

export default function VisitorsChart() {
  return (
    <LineChart data={data} config={config} margin={{ right: 16 }} aria-label="Monthly visitors">
      <LineChart.Grid />
      <LineChart.XAxis dataKey="month" />
      <LineChart.YAxis width={40} />
      <LineChart.Series dataKey="visitors" type="monotone" strokeWidth={2} />
      <LineChart.Tooltip />
      <LineChart.Legend />
    </LineChart>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="shadcn"
npx shadcn@latest add @kind-ui/line-chart
```

```bash tab="npm"
npm install @kind-ui/charts motion recharts
```

## Composition [#composition]

```text
LineChart
├── LineChart.Background
├── LineChart.Grid
├── LineChart.XAxis
├── LineChart.YAxis
├── LineChart.Series
├── LineChart.Tooltip
├── LineChart.Legend
└── LineChart.Content
```

`LineChart` holds the data, the series config and the accessible name, and draws only the parts you add. Add one `LineChart.Series` per line. The tooltip and legend read their labels and colors from `config`. `LineChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Series [#series]

Each `LineChart.Series` plots the `dataKey` it names, and takes its label and color from the matching `config` entry. Set `type` for the curve (`linear` by default, `monotone` for a smooth line, `step` for steps), and `strokeDasharray` to dash a line, like a target:

<Example caption="Press Revenue or Target in the legend to highlight that line.">
<Comparison />

```tsx
"use client";

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

const data = [
  { month: "Jan", revenue: 42, target: 40 },
  { month: "Feb", revenue: 47, target: 44 },
  { month: "Mar", revenue: 45, target: 48 },
  { month: "Apr", revenue: 53, target: 52 },
  { month: "May", revenue: 58, target: 56 },
  { month: "Jun", revenue: 64, target: 60 },
];

const config = {
  revenue: { label: "Revenue", color: "#0f8b8d" },
  target: { label: "Target", color: "#e07a2f" },
} satisfies SeriesConfig;

export default function RevenueChart() {
  return (
    <LineChart
      data={data}
      config={config}
      margin={{ right: 16 }}
      aria-label="Revenue against target, in thousands of dollars"
    >
      <LineChart.Grid />
      <LineChart.XAxis dataKey="month" />
      <LineChart.YAxis width={40} />
      <LineChart.Series dataKey="revenue" type="monotone" strokeWidth={2} />
      <LineChart.Series dataKey="target" strokeDasharray="6 4" dot={false} />
      <LineChart.Tooltip />
      <LineChart.Legend />
    </LineChart>
  );
}
```
</Example>

A `null` value leaves a gap in the line. Pass `connectNulls` to the series to draw across it instead.

### Legend and Keyboard [#legend-and-keyboard]

Pressing a legend item highlights its line and dims the others, and screen readers hear "Highlighted Revenue." Press it again, or press Escape, to clear it. To hide and show lines from the legend instead, see [Legend](../building-blocks/legend.mdx).

Focus the chart and press the arrow keys to move between points, which shows the tooltip, and Escape to dismiss it. Screen readers hear these instructions when the chart gets focus.

### Points and Dashes [#points-and-dashes]

Lines have a dot at each point. Pass `dot={false}` to hide them, or `pointStyle="border"` or `"colored-border"` for outlined points. With a numeric `strokeDasharray`, `dashAnimation` moves the dashes along the line:

```tsx
<LineChart.Series
  dataKey="target"
  strokeDasharray="6 4"
  dashAnimation={{ durationMs: 1000 }}
/>
```

Set `material="clay"` or `"glow"` on a series for a finish; see [Materials](../guides/materials.mdx).

### Motion [#motion]

Lines draw in from left to right when the chart mounts. Set `animate` to change the direction or the duration, or `animate={false}` to turn it off:

```tsx
<LineChart animate={{ revealDirection: "center-out", revealDurationMs: 800 }} {...props}>
```

`revealDirection` is `left-to-right`, `right-to-left`, `center-out` or `edges-in`. When the reader prefers reduced motion, lines appear without drawing in. See [Motion](../guides/motion.mdx).

### Loading [#loading]

Set `loading` while the data is on its way. The chart keeps its size and shows a placeholder line that sweeps across the plot, or holds still when the reader prefers reduced motion. Screen readers hear `loadingLabel` ("Loading chart" by default). The legend and tooltip come back when `loading` turns off:

```tsx
<LineChart loading={isPending} loadingLabel="Loading visitors" {...props}>
```

### Background [#background]

Add `LineChart.Background` for a decorative pattern behind the plot: `pinpoints`, `crossings` or `waves`. It adds nothing to the tooltip, legend or accessible name.

```tsx
<LineChart.Background pattern="crossings" opacity={0.15} />
```

## API Reference [#api-reference]

### LineChart [#linechart]

### LineChartOptions

| 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.                                                                       |
| `loading?`               | `boolean \| undefined`                                                                                                                                                                                                                               | Shows a placeholder plot and hides the legend and tooltip while the data is on its way.                                                            |
| `loadingLabel?`          | `string \| undefined`                                                                                                                                                                                                                                | What screen readers hear while `loading` is on. Default: `"Loading chart"`                                                                         |
| `animate?`               | `boolean \| LineAnimation \| undefined`                                                                                                                                                                                                              | Draws the lines in on mount. Pass options to change the direction or duration, or `false` to turn it off. Reduced motion skips it. Default: `true` |
| `config`                 | `Readonly<Record<string, { label?: string; color: SeriesColor; pattern?: FillPattern; icon?: React.ComponentType; legendShape?: NonNullable<React.ComponentProps<typeof Symbols>["type"]>; formatValue?: (value: ValueType) => React.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.                                                            |
| `aria-label?`            | `string \| undefined`                                                                                                                                                                                                                                | The chart's accessible name. Pass this or `aria-labelledby`.                                                                                       |
| `aria-labelledby?`       | `string \| undefined`                                                                                                                                                                                                                                | The id of an element that names the chart. Pass this or `aria-label`.                                                                              |
| `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.                                                             |
| `data?`                  | `readonly unknown[] \| undefined`                                                                                                                                                                                                                    | The rows to plot. Each series reads its `dataKey` from every row.                                                                                  |

### LineChart.Series [#linechartseries]

### LineSeriesOptions

| Prop                | Type                                        | Description                                                                                        |
| ------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `seriesKey?`        | `string \| undefined`                       | The `config` key for this series. Required when `dataKey` is a function or a number.               |
| `pointStyle?`       | `"border" \| "colored-border" \| "default"` | How each point is painted. A `dot` you pass replaces it. Default: `"default"`                      |
| `activePointStyle?` | `"border" \| "colored-border" \| "default"` | How the inspected point is painted. An `activeDot` you pass replaces it.                           |
| `material?`         | `"clay" \| "glow" \| "plain"`               | A finish for the line. A custom `shape` or `filter` replaces it. Default: `"plain"`                |
| `dashAnimation?`    | `false \| LineDashAnimation \| undefined`   | Moves the dashes along the line. Needs a numeric `strokeDasharray`, like `"6 4"`. Default: `false` |

<Caption>
`LineChart` and `LineChart.Series` also take every prop of Recharts' [LineChart](https://recharts.github.io/en-US/api/LineChart/) and [Line](https://recharts.github.io/en-US/api/Line/), like `margin`, `type` and `connectNulls`.
</Caption>