# Brush

> Filter a Cartesian chart to a selected data range.

Source: https://www.honestui.com/docs/charts/ui/brush

## Usage [#usage]

Add `<AreaChart.Brush />` as a child of the chart root. It renders a miniature of the full dataset with a draggable selection window. Narrowing the window filters the main chart while the miniature keeps the full range visible.

The built-in canvas brush is pointer-operated. If choosing a data range is required, provide equivalent range inputs, date controls, or another keyboard-operable filter outside the chart.

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

```tsx
import { AreaChart } from "honestui/charts";

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

## Example [#example]

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

> 
  
    Drag either handle to resize the range, or drag the selected region to pan without changing
    its width. The main plot can also move the visible window because the brush uses ECharts
    `dataZoom`. These pointer interactions need an equivalent external control when range changes
    are part of the core task.
  


## Supported Charts [#supported-charts]

The brush is available on the cartesian charts, `AreaChart`, `LineChart`, and `BarChart`. Attach it exactly the same way on each:

```tsx
<LineChart.Brush />
<BarChart.Brush />
```

The miniature mirrors the chart it belongs to. Area charts draw filled areas, line charts draw strokes only, and bar charts draw rounded bars. 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 pie chart, which has no continuous axis to zoom.

## Reacting to the Range [#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 });

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

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

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

## Rendering [#rendering]

The brush uses a second ECharts grid with mirrored copies of the visible series. A transparent native `dataZoom` slider supplies dragging and panning, while the selection frame, dimmed regions, handles, and range labels are drawn as synchronized canvas elements.

## API Reference [#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.