{"id":17195780,"url":"https://github.com/kenns29/react-svg-brush","last_synced_at":"2025-04-13T20:41:56.592Z","repository":{"id":57345951,"uuid":"201800239","full_name":"kenns29/react-svg-brush","owner":"kenns29","description":"A React-based brush library that emulates the d3-brush behavior.","archived":false,"fork":false,"pushed_at":"2020-01-31T06:35:14.000Z","size":388,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-27T11:02:35.045Z","etag":null,"topics":["react-library","visualization-library"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kenns29.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-11T18:24:50.000Z","updated_at":"2024-11-18T16:04:00.000Z","dependencies_parsed_at":"2022-09-17T22:51:25.836Z","dependency_job_id":null,"html_url":"https://github.com/kenns29/react-svg-brush","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenns29%2Freact-svg-brush","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenns29%2Freact-svg-brush/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenns29%2Freact-svg-brush/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenns29%2Freact-svg-brush/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kenns29","download_url":"https://codeload.github.com/kenns29/react-svg-brush/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248782265,"owners_count":21160716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["react-library","visualization-library"],"created_at":"2024-10-15T01:51:24.104Z","updated_at":"2025-04-13T20:41:56.550Z","avatar_url":"https://github.com/kenns29.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React SVG Brush\n\nThe [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.\n\nFeel free to improve this library by filing issues or making pull requests in the library [github repo](https://github.com/kenns29/react-svg-brush).\n\n## Examples\n\n**1D Brush**\n\n[\u003cimg alt=\"brush-1d\" src=\"docs/brush-1d.png\"\u003e\u003c/img\u003e](https://codepen.io/kennsmacintosh/pen/yLBPGbN)\n\n**2D Brush**\n\n[\u003cimg alt=\"brush-1d\" src=\"docs/brush-2d.png\" width=\"200px\"\u003e\u003c/img\u003e](https://codepen.io/kennsmacintosh/pen/dybZwQj)\n\n**Brush Snapping (Transition)**\n\n[\u003cimg alt=\"brush-1d\" src=\"docs/brush-1d.png\"\u003e\u003c/img\u003e](https://codepen.io/kennsmacintosh/pen/oNvoVaY)\n\n## Why Yet Another Brush Library\n\nThe [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:\n\n- 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.\n- 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.\n\nThe 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.\n\n## Installation\n\n```\nnpm install react-svg-brush\n```\n\n## Example Usage\n\n```javascript\nimport React, {Component} from 'react';\nimport SVGBrush from 'react-svg-brush';\n\n...\n\nexport default class App extends Component {\n  onBrushStart = ({target, type, selection, sourceEvent})=\u003e{...}\n  onBrush = ({target, type, selection, sourceEvent})=\u003e{...}\n  onBrushEnd = ({target, type, selection, sourceEvent})=\u003e{...}\n  renderBrush = () =\u003e (\n    \u003cSVGBrush\n      // Defines the boundary of the brush.\n      // Strictly uses the format [[x0, y0], [x1, y1]] for both 1d and 2d brush.\n      // Note: d3 allows the format [x, y] for 1d brush.\n      extent={[[x0, y0], [x1, y1]]}\n      // Obtain mouse positions relative to the current svg during mouse events.\n      // By default, getEventMouse returns [event.clientX, event.clientY]\n      getEventMouse={event =\u003e {\n        const {clientX, clientY} = event;\n        const {left, top} = this.svg.getBoundingClientRect();\n        return [clientX - left, clientY - top];\n      }}\n      brushType=\"2d\" // \"x\"\n      onBrushStart={this.onBrushStart}\n      onBrush={this.onBrush}\n      onBrushEnd={this.onBrushEnd}\n    /\u003e\n  )\n  render() {\n    return (\n      \u003csvg ref={input =\u003e (this.svg = input)}\u003e\n        {this.renderBrush()}\n      \u003c/svg\u003e\n    );\n  }\n}\n```\n\nThe following shows the DOM structure generated by React SVG Brush:\n\n```html\n\u003cg class=\"brush\"\u003e\n  \u003crect class=\"overlay\" pointer-events=\"all\" cursor=\"crosshair\" fill=\"none\" x=\"40\" y=\"10\" width=\"380\" height=\"350\"\u003e\u003c/rect\u003e\n  \u003crect class=\"selection\" cursor=\"move\" fill=\"#777\" fill-opacity=\"0.3\" stroke=\"#fff\" shape-rendering=\"crispEdges\" x=\"217.80859375\" y=\"144.046875\" width=\"30.26171875\" height=\"185.546875\"\u003e\u003c/rect\u003e\n  \u003crect class=\"handle handle--n\" cursor=\"ns-resize\" x=\"212.80859375\" y=\"139.046875\" width=\"40.26171875\" height=\"10\" fill=\"none\" pointer-events=\"visible\"\u003e\u003c/rect\u003e\n  \u003crect class=\"handle handle--e\" cursor=\"ew-resize\" x=\"243.0703125\" y=\"139.046875\" width=\"10\" height=\"195.546875\" fill=\"none\" pointer-events=\"visible\"\u003e\u003c/rect\u003e\n  \u003crect class=\"handle handle--s\" cursor=\"ns-resize\" x=\"212.80859375\" y=\"324.59375\" width=\"40.26171875\" height=\"10\" fill=\"none\" pointer-events=\"visible\"\u003e\u003c/rect\u003e\n  \u003crect class=\"handle handle--w\" cursor=\"ew-resize\" x=\"212.80859375\" y=\"139.046875\" width=\"10\" height=\"195.546875\" fill=\"none\" pointer-events=\"visible\"\u003e\u003c/rect\u003e\n  \u003crect class=\"handle handle--nw\" cursor=\"nwse-resize\" x=\"212.80859375\" y=\"139.046875\" width=\"10\" height=\"10\" fill=\"none\" pointer-events=\"visible\"\u003e\u003c/rect\u003e\n  \u003crect class=\"handle handle--ne\" cursor=\"nesw-resize\" x=\"243.0703125\" y=\"139.046875\" width=\"10\" height=\"10\" fill=\"none\" pointer-events=\"visible\"\u003e\u003c/rect\u003e\n  \u003crect class=\"handle handle--se\" cursor=\"nwse-resize\" x=\"243.0703125\" y=\"324.59375\" width=\"10\" height=\"10\" fill=\"none\" pointer-events=\"visible\"\u003e\u003c/rect\u003e\n  \u003crect class=\"handle handle--sw\" cursor=\"nesw-resize\" x=\"212.80859375\" y=\"324.59375\" width=\"10\" height=\"10\" fill=\"none\" pointer-events=\"visible\"\u003e\u003c/rect\u003e\n\u003c/g\u003e\n```\n\nMore demo code can be found in this repo, [React SVG Brush Example](https://github.com/kenns29/react-svg-brush-example).\n\n## API Reference\n\n### Attributes\n\n`brushType` **(String, Required)**\n\n- Default: `'2d'`\n\nChoose 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.\n\n`extent` **(Array, Required)**\n\n- Default: `[[0, 0], [1, 1]]`\n\nDefines 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.\n\n`selection` **(Array, Optional)**\n\n- Default: `undefined`\n\nManually 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.  \n\n### Methods\n\n`getEventMouse` **(Function, Optional)**\n\n- Default: `event =\u003e [event.clientX, event.clientY]`\n\nObtain 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).\n\n`onBrushStart` **(Function, Optional)**\n\nThe callback function when the brushing interaction starts (i.e. mouse click). This function receives one object as the argument, which contains the following attributes:\n\n- `target` - Refers to the brush object itself (the React component).\n- `type` - The type of the callback, in this case, it is `start`\n- `selection` - The brush selection when the brush starts.\n- `sourceEvent` - The React `SyntheticEvent` of the brush, in this case, it is a pointer event.\n\n`onBrush` **(Function, Optional)**\n\nThe callback function during brush interaction (i.e. while dragging the brush). This function receives one object as the argument, which contains the following attributes:\n\n- `target` - Refers to the brush object itself (the React component).\n- `type` - The type of the callback, in this case, it is `brush`\n- `selection` - The changed brush selection during the interaction.\n- `sourceEvent` - The React `SyntheticEvent` of the brush, in this case, it is a pointer event.\n\n`onBrushEnd` **(Function, Optional)**\n\nThe 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:\n\n- `target` - Refers to the brush object itself (the React component).\n- `type` - The type of the callback, in this case, it is `end`\n- `selection` - The changed brush selection at the end of the brush interaction.\n- `sourceEvent` - The React `SyntheticEvent` of the brush, in this case, it is a pointer event.\n\n## Change Log\n\nRefer to the [CHANGELOG.md](CHANGELOG.md) file.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenns29%2Freact-svg-brush","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkenns29%2Freact-svg-brush","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenns29%2Freact-svg-brush/lists"}