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