Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kenns29/react-svg-brush
A React-based brush library that emulates the d3-brush behavior.
https://github.com/kenns29/react-svg-brush
react-library visualization-library
Last synced: 3 months ago
JSON representation
A React-based brush library that emulates the d3-brush behavior.
- Host: GitHub
- URL: https://github.com/kenns29/react-svg-brush
- Owner: kenns29
- Created: 2019-08-11T18:24:50.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-01-31T06:35:14.000Z (almost 5 years ago)
- Last Synced: 2024-09-21T15:29:02.111Z (4 months ago)
- Topics: react-library, visualization-library
- Language: JavaScript
- Homepage:
- Size: 379 KB
- Stars: 7
- Watchers: 4
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# React SVG Brush
The [react-svg-brush](https://www.npmjs.com/package/react-svg-brush) is a React-based brush library that emulates the [d3-brush](https://github.com/d3/d3-brush) behavior. It renders the brush using React virtual DOM.
Feel free to improve this library by filing issues or making pull requests in the library [github repo](https://github.com/kenns29/react-svg-brush).
## Examples
**1D Brush**
[
](https://codepen.io/kennsmacintosh/pen/yLBPGbN)
**2D Brush**
[
](https://codepen.io/kennsmacintosh/pen/dybZwQj)
**Brush Snapping (Transition)**
[](https://codepen.io/kennsmacintosh/pen/oNvoVaY)
## Why Yet Another Brush Library
The [d3-brush](https://github.com/d3/d3-brush) library is commonly used for data selection within visualizations. It enables data selection through dragging on the visualization interface (holding the left mouse and move the curser). It also renders the brushed area directly on the visualization. However, there are several drawbacks when using [d3-brush](https://github.com/d3/d3-brush) directly inside a React-based application:
- d3-brush directly modifies the DOM, which also means customization of the brush behavior/view has to be done directly on the DOM, violating the best practices in React.
- Using d3-brush inside a React component typically requires using the react lifecycle methods, e.g. `componentDidUpdate`, adding complexity in the implementation of the React component.
The React SVG Brush library emulates the d3-brush library DOM structure (95% identical) and functionalities but renders the Brush completely using the React virtual DOM, making it easy for applications that use d3-brush to switch to this library to adhere to the React best practices.
## Installation
```
npm install react-svg-brush
```
## Example Usage
```javascript
import React, {Component} from 'react';
import SVGBrush from 'react-svg-brush';
...
export default class App extends Component {
onBrushStart = ({target, type, selection, sourceEvent})=>{...}
onBrush = ({target, type, selection, sourceEvent})=>{...}
onBrushEnd = ({target, type, selection, sourceEvent})=>{...}
renderBrush = () => (
{
const {clientX, clientY} = event;
const {left, top} = this.svg.getBoundingClientRect();
return [clientX - left, clientY - top];
}}
brushType="2d" // "x"
onBrushStart={this.onBrushStart}
onBrush={this.onBrush}
onBrushEnd={this.onBrushEnd}
/>
)
render() {
return (
(this.svg = input)}>
{this.renderBrush()}
);
}
}
```
The following shows the DOM structure generated by React SVG Brush:
```html
```
More demo code can be found in this repo, [React SVG Brush Example](https://github.com/kenns29/react-svg-brush-example).
## API Reference
### Attributes
`brushType` **(String, Required)**
- Default: `'2d'`
Choose the brush type. Three brush types are supported: `2d`, `x`, and `y` (`y` is still experimental). The `2d` allows dragging on all sides and corners, whereas the `x` and `y` brush only allows dragging on horizontal and vertical directions respectively.
`extent` **(Array, Required)**
- Default: `[[0, 0], [1, 1]]`
Defines the brush boundary. The array `[[x0, y0], [x1, y1]]` defines the bounding box of the brush boundary, where `[x0, y0]` represents the point in top-left corner and `[x1, y1]` represents the point in the bottom-right corner.
`selection` **(Array, Optional)**
- Default: `undefined`
Manually set the selection of the brush. This is typically used when setting the initial state of the brush, or when post processing the brush selections, e.g. brush snapping. Like the `extent`, the `selection` is also defined by a bounding box array `[[x0, y0], [x1, y1]]`. When the `selection` parameter is defined, the brush will be rendered according to the selection. When the `selection` parameter is set to `null`, the brush will be cleared. When the `selection` parameter is `undefined`, the brush rendering will be automatically controlled during the interactions.
### Methods
`getEventMouse` **(Function, Optional)**
- Default: `event => [event.clientX, event.clientY]`
Obtain the mouse position given the pointer event. It must return an array of `[x, y]` that specifies the position of the mouse. By default, it returns `[event.clientX, event.clientY]` which is the position relative to the web page. The default behavior of this function is typically overwritten, because it is more common to use the position relative to the container of the brush (e.g. the SVG).
`onBrushStart` **(Function, Optional)**
The callback function when the brushing interaction starts (i.e. mouse click). This function receives one object as the argument, which contains the following attributes:
- `target` - Refers to the brush object itself (the React component).
- `type` - The type of the callback, in this case, it is `start`
- `selection` - The brush selection when the brush starts.
- `sourceEvent` - The React `SyntheticEvent` of the brush, in this case, it is a pointer event.
`onBrush` **(Function, Optional)**
The callback function during brush interaction (i.e. while dragging the brush). This function receives one object as the argument, which contains the following attributes:
- `target` - Refers to the brush object itself (the React component).
- `type` - The type of the callback, in this case, it is `brush`
- `selection` - The changed brush selection during the interaction.
- `sourceEvent` - The React `SyntheticEvent` of the brush, in this case, it is a pointer event.
`onBrushEnd` **(Function, Optional)**
The callback function at the end of brush interaction (i.e. mouse up). This function receives one object as the argument, which contains the following attributes:
- `target` - Refers to the brush object itself (the React component).
- `type` - The type of the callback, in this case, it is `end`
- `selection` - The changed brush selection at the end of the brush interaction.
- `sourceEvent` - The React `SyntheticEvent` of the brush, in this case, it is a pointer event.
## Change Log
Refer to the [CHANGELOG.md](CHANGELOG.md) file.