# Brush

A zoom brush that filters a cartesian chart to a draggable data range.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).





## Usage [#usage]

Add `<Brush />` inside the chart root. Its presence renders a miniature of the full dataset with a draggable selection window. Narrowing the window filters the main plot while the miniature retains the full context.

Set `xDataKey` on the root, or `dataKey` on `<XAxis />`, so the range labels use the category beneath each handle.

```tsx
import { ChartcnAreaChart } from "@/components/chart/area-chart";

<ChartcnAreaChart data={data} config={chartConfig} xDataKey="month">
  <ChartcnAreaChart.XAxis dataKey="month" />
  <ChartcnAreaChart.Brush startIndex={2} endIndex={10} />
  <ChartcnAreaChart.Area dataKey="desktop" />
</ChartcnAreaChart>;
```

## Example [#example]

<ComponentPreview base="chartgpu" className="mb-0" name="area-chart-demo" title="<ChartcnAreaChart.Brush />">
  <AreaChartDemo />
</ComponentPreview>

Drag either handle to resize the range, or drag the selected region to move it without changing its width. Handle labels fade in while the pointer is over the brush. Mouse, touch, and pen input are supported.

## Supported Charts [#supported-charts]

Brush is available on the cartesian charts: Area, Line, Bar, and Composed Chart. Attach it the same way to each root.

```tsx
<ChartcnLineChart.Brush />
<ChartcnBarChart.Brush />
<ChartcnComposedChart.Brush />
```

The miniature uses the full dataset and inherits the parent chart's series colors and selection opacity. The primary plot, x-axis labels, tooltip values, and range labels update to the same visible indices.

Brush is hidden from non-cartesian charts because pie, scatter, financial, and heatmap plots do not share this category-window interaction.

## Reacting to the Range [#reacting-to-the-range]

Filtering is automatic. Pass `onBrushChange` when content outside the chart must follow the selection.

```tsx
const [range, setRange] = useState({
  startIndex: 0,
  endIndex: data.length - 1,
});

<ChartcnAreaChart
  data={data}
  config={chartConfig}
  onBrushChange={setRange}
  xDataKey="month"
>
  <ChartcnAreaChart.Brush />
  <ChartcnAreaChart.Area dataKey="desktop" />
</ChartcnAreaChart>;
```

`onBrushChange` returns inclusive data indices, so external content can read the corresponding rows directly.

## API Reference [#api-reference]

### Brush [#brush]

| Prop         | Type     | Default         | Description                                    |
| ------------ | -------- | --------------- | ---------------------------------------------- |
| `startIndex` | `number` | `0`             | Inclusive index at the left edge of the range. |
| `endIndex`   | `number` | Last data index | Inclusive index at the right edge.             |

### Root [#root]

| Prop            | Type                                                        | Default | Description                                     |
| --------------- | ----------------------------------------------------------- | ------- | ----------------------------------------------- |
| `xDataKey`      | `string`                                                    | -       | Data key used for axis and range labels.        |
| `onBrushChange` | `(range: { startIndex: number; endIndex: number }) => void` | -       | Fires as the selected range changes.            |
| `showBrush`     | `boolean`                                                   | `false` | Enables Brush without composing the child part. |