---
title: Brush
description: A zoom brush that filters the chart down to a draggable range of the data.
image: /og/og-image.png
---

## Usage

Add `<EChartsAreaChart.Brush />` as a child of the chart root. Its presence renders the brush footer — a miniature of the **full** dataset with a draggable selection window over it. Narrowing that window filters the main chart to the selected range; the miniature always keeps showing everything, so you never lose your place.

Set `xDataKey` on the root (or `dataKey` on `<XAxis />`) so the handles can label themselves with the category under each edge.

```tsx
import { EChartsAreaChart } from "@/components/evilcharts/charts/echarts-area-chart";

<EChartsAreaChart data={data} config={chartConfig} xDataKey="date">
  <EChartsAreaChart.XAxis dataKey="date" />
  <EChartsAreaChart.Brush formatLabel={(value) => String(value)} />
  <EChartsAreaChart.Area dataKey="desktop" variant="gradient" />
</EChartsAreaChart>;
```

## Example

<ComponentPreview className="mb-0" title="<EChartsAreaChart.Brush />" name="ex-brush-echarts-area-chart" />

> 
  
    Drag either handle to resize the range, or drag the selected region itself to pan without
    changing its width. Handle labels fade in while the pointer is over the brush. Because the
    ECharts brush is backed by a native `dataZoom`, the main plot is draggable too — drag the chart
    itself to slide the visible window, and the brush follows along.
  


## Supported Charts

The brush is available on the cartesian charts — `EChartsAreaChart`, `EChartsLineChart`, `EChartsBarChart`, and `EChartsComposedChart`. Attach it exactly the same way on each:

```tsx
<EChartsLineChart.Brush />
<EChartsBarChart.Brush />
<EChartsComposedChart.Brush />
```

The miniature mirrors the chart it belongs to. Area and composed charts draw filled areas, line charts draw strokes only, and bar charts draw rounded bars — and it inherits the parent chart's stacking and series colors, dimming alongside the main plot when a series is selected.

The brush is hidden while the chart is in its loading state, and it never renders for the non-cartesian charts (pie, radar, radial, sankey), which have no continuous axis to zoom.

## Reacting to the Range

Filtering the chart is automatic. Pass `onChange` when something *outside* the chart needs to follow along, such as a heading that reports the visible window:

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

<EChartsAreaChart data={data} config={chartConfig} xDataKey="date">
  <EChartsAreaChart.Brush onChange={setRange} />
  <EChartsAreaChart.Area dataKey="desktop" variant="gradient" />
</EChartsAreaChart>;

// data[range.startIndex].date → data[range.endIndex].date
```

`onChange` fires with data **indices**, not values, so look the labels up on your own rows.

## How It Differs from Recharts

Same JSX, same props, same behavior — but ECharts renders to a `<canvas>`, so the brush is built differently underneath. The miniature is a real second ECharts grid holding mirrored copies of every series. A fully transparent native `dataZoom` slider sits on top of it and supplies the drag interaction, while everything you actually see — the rounded selection frame, the dimmed sides, the grip-dot handle pills, and the range labels — is drawn as canvas elements that track the selection directly.

The practical differences: the main plot gains drag-to-pan for free, and the footer is a close reconstruction of the Recharts `EvilBrush` rather than a pixel-identical copy of it.

## API Reference

<ApiHeading>Brush</ApiHeading>

Composed as a child of the chart root. It renders nothing itself — its presence turns the brush footer on, and its props configure it.


  ### `height`

type: `number` · default: `56`

Height of the brush preview strip in pixels.
  ### `formatLabel`



string">
    Formats the range-handle labels from the category under each edge. Defaults to the raw value.
  ### `onChange`



void">
    Fires as the selection moves, with the inclusive data indices of the visible range.


<ApiHeading>Root</ApiHeading>


  ### `xDataKey`

type: `string`

The data key the handle labels read from. Falls back to the `<XAxis />` `dataKey`, then to the
    first data column no series has claimed.