react-brush 🚧

Render an svg with a highlightable area.

Installation

yarn add react-brush

Basic Usage

The default export of react-brush is a component.

import ReactBrush from 'react-brush';

// ...
  <ReactBrush height={200} width={500} />
// ...

This will render an svg with a brush overlay that is enabled when the user presses and holds mouse button 0 for a short time ( >= 300ms) or clicks, holds and begins to drag. The selected region will be displayed while the brush is in progress. Callbacks can be registered to handle the start, stop and change of a brush action.

<ReactBrush
  height={200}
  width={500}
  onBrushStart={handleBrushStart}
  onBrushEnd={handleBrushEnd}
  onBrushChange={handleBrushChange}
/>

The callbacks will receive a single object parameter with the following type:

{
  x: number,       // x and y represent the top left corner of the selected region relative
  y: number,       // to the origin of the svg's viewable area

  width: number,   // the width and height of selected region
  height: number,  
}

react-brush also exports a BrushedArea component that can be used to customize the selected area. Pass it as the prop brushedArea to the ReactBrush component.

<ReactBrush
  height={200}
  width={500}
  brushedArea={<BrushedArea fullHeight />}
/>

The brushedArea prop can alternatively be a render callback that will be passed a single object parameter with the shape { brush: Object, container: Object }. The brush property is an object of the same type as that passed to the brush callbacks. The container property is an object with the shape { top: number, bottom: number, left: number, right: number } describing the position of the ReactBrush container in the document.

<ReactBrush
  height={200}
  width={500}
  brushedArea={({ container, brush }) => {
    /* do something awesome */
  }}
/>

react-brush only provides a brushed area during a brush and the callbacks to let you know what was brushed. How the selection should affect your elements is up to you to implement.

react-brush composes well with other interactive graphical elements because it gets out of the way when a brush isn't active and won't interfere with other mouse events.

See the demo for some working examples.

API:

<ReactBrush> Props

Property | Type | Required | Default | Description :-----------|:----------|:----------|:----------|:---------- width | number | yes | undefined | The width of the brush container height | number | yes | undefined | The height of the brush container onBrushStart | function | no | undefined | The callback to use if any when a brush is started (the user presses mouse button 0) onBrushStop | function | no | undefined | The callback to use if any when a brush is stopped (the user releases mouse button 0) onBrushChange | function | no | undefined | The callback to use if any when a brush is changed (the user drags while holding down mouse button 0) brushedArea | function or element | no | <BrushedArea /> | The element or render callback to use to render the brushed area tag | string ("svg" or "g") | no | svg | The base component used to render the ReactBrush. This can either be an svg or a g. In either case, props other than those specified here are passed on to the base component (if svg is used, width and height are also passed on). mouseMoveThreshold| number | no | 5 | The number of pixels that the mouse needs to move after a mouse down before the brush starts. mouseDownThreshold | number | no | 500 | The number of milliseconds after a mouse down before the start of a brush.

<BrushedArea> Props

Property | Type | Required | Default | Description :-----------|:----------|:----------|:----------|:---------- fullHeight | boolean | no | false | the brushed area will take up the full height of its container fullWidth | boolean | no | false | the brushed area will take up the full width of its container