react-svg-pan-zoom is a React component that adds pan and zoom features to the SVG images. It helps to display big SVG images in a small space.
available at http://chrvadala.github.io/react-svg-pan-zoom/
This component can work in four different modes depending on the selected tool:
- With the tool pan the user can move the image and drag it around within the viewer, but can't interact with SVG child elements.
- With the tool zoom the user can scale the image either with a point click or selecting a region to zoom the specified area, but can't interact with SVG child elements.
- With the tool none the user can interact with SVG child elements and trigger events.
- With the tool auto the user can interact with SVG child elements, perform pan (dragging the image), zoom in (double click), zoom out (double click + shift).
- Zoom detection performed through pinch and scroll (optional)
- Autopan when the mouse is close to the edge of the viewer (optional)
- Each callback function receives (x,y) coords mapped to the real size of the SVG
- Programmatically controllable
- Event info managed lazily to ensure high performance
- ES6 syntax
npm install --save react-svg-pan-zoom
bower install react-svg-pan-zoom
import React from 'react';
import {ReactSVGPanZoom} from 'react-svg-pan-zoom';
class Demo extends React.Component {
constructor(props, context) {
super(props, context);
this.Viewer = null;
}
componentDidMount() {
this.Viewer.fitToViewer();
}
render() {
return (
<div>
<button onClick={event => this.Viewer.zoomOnViewerCenter(1.1)}>Zoom in</button>
<button onClick={event => this.Viewer.fitSelection(40, 40, 200, 200)}>Zoom area</button>
<button onClick={event => this.Viewer.fitToViewer()}>Fit</button>
<hr/>
<ReactSVGPanZoom
style={{outline: "1px solid black"}}
width={500} height={500} ref={Viewer => this.Viewer = Viewer}
onClick={event => console.log('click', event.x, event.y, event.originalEvent)}
onMouseMove={event => console.log('move', event.x, event.y)} >
<svg width={900} height={800}>
<-- put here your SVG content -->
</svg>
</ReactSVGPanZoom>
</div>
);
}
}
width
– required – width of the viewer displayed on screen (if you want to omit this see Autosize)height
– required – height of the viewer displayed on screen (if you want to omit this see Autosize)value
- inject and lock the viewer to a specific valueonChangeValue
- callback called when the viewer changes its valuefn(value: object)
tool
- inject and lock the viewer to a specific tool ( one ofnone
,pan
,zoom-in
,zoom-out
,auto
)onChangeTool
- callback called when the viewer changes the used toolfn(tool: string)
SVGBackground
- background of the SVG (default color: white)background
– background of the viewer (default color: dark grey)style
- CSS style of the viewerclassName
- CSS class of the viewerdetectWheel
- detect zoom operation performed through pinch gesture or mouse scrolldetectAutoPan
- perform PAN if the mouse is on the border of the viewertoolbarPosition
- toolbar position (one ofnone
,top
,right
,bottom
,left
)customToolbar
- React component with custom toolbarmodifierKeys
- array with modifier keys used with the toolauto
to swapzoom in
andzoom out
(Accepted value)preventPanOutside
- if false the user can move the image outside the viewerscaleFactor
- how much scale in or out (default: 1.1 = 110%)onClick
- handler* for clickfn(viewerEvent: ViewerMouseEvent)
onDoubleClick
- handler* for dblclickfn(viewerEvent: ViewerMouseEvent)
onMouseUp
- handler* for mouseupfn(viewerEvent: ViewerMouseEvent)
onMouseMove
- handler* for mousemovefn(viewerEvent: ViewerMouseEvent)
onMouseDown
- handler* for mousedownfn(viewerEvent: ViewerMouseEvent)
onTouchStart
- handler* for mousedownfn(viewerEvent: ViewerTouchEvent)
onTouchMove
- handler* for mousedownfn(viewerEvent: ViewerTouchEvent)
onTouchEnd
- handler* for mousedownfn(viewerEvent: ViewerTouchEvent)
onTouchCancel
- handler* for mousedownfn(viewerEvent: ViewerTouchEvent)
* handler available only with the tool none
or auto
pan( SVGDeltaX, SVGDeltaY )
- Apply a panzoom(SVGPointX, SVGPointY, scaleFactor)
- Zoom in or out the SVGfitSelection(selectionSVGPointX, selectionSVGPointY, selectionWidth, selectionHeight)
- Fit an SVG area to viewerfitToViewer()
- Fit all SVG to ViewersetPointOnViewerCenter(SVGPointX, SVGPointY, zoomLevel)
- Set a point on Viewer centerreset()
- Reset Viewer view to defaultzoomOnViewerCenter(scaleFactor)
- Zoom SVG on centergetValue()
- Get current viewer valuesetValue(value)
- Through this method you can set a new valuegetTool()
- Get current toolsetTool(tool)
- Set a tool (one ofnone
,pan
,zoom-in
,zoom-out
,auto
)
To your event handlers will be passed an instance of ViewerMouseEvent
or ViewerTouchEvent
(as the case). They have some useful attributes that map event positions to SVG coords.
If, for your purpose, you need the original React event instance (SyntheticEvent
), you can get it through event.originalEvent
. You can't use event in async way, see React Event Pooling for more information.
originalEvent: SyntheticEvent
- The original React eventSVGViewer: SVGSVGElement
- Reference to SVGViewerpoint: object
- coordinates (x,y) of the event mapped to SVG coordinatesx: number
- x coordinate of the event mapped to SVG coordinatesy: number
- y coordinate of the event mapped to SVG coordinatesscaleFactor: number
- zoom leveltranslationX: number
- x delta from the viewer origintranslationY: number
- y delta from the viewer originpreventDefault(): void
- aliasoriginalEvent.preventDefault()
stopPropagation(): void
- aliasoriginalEvent.stopPropagation()
originalEvent: SyntheticEvent
- The original React eventSVGViewer: SVGSVGElement
- Reference to SVGViewerpoints: array[{x, y, identifier}]
- array with coordinates (x, y, identifier) of the touches mapped to SVG coordinateschangedPoints: array[{x, y, identifier}]
- coordinates (x, y, identifier) of the changed touches mapped to SVG coordinatesscaleFactor: number
- zoom leveltranslationX: number
- x delta from the viewer origintranslationY: number
- y delta from the viewer originpreventDefault(): void
- aliasoriginalEvent.preventDefault()
stopPropagation(): void
- aliasoriginalEvent.stopPropagation()
- Basic - This project show how to use the component in a scenario when is not required a full control on the internal state. This is the easist React SVG Pan Zoom usage.
- Controlled state - This advanced project show a scenario in which the parent component has a full control of the svg viewer. The state is owned by the parent and injected on the viewer throught
props
. Any state change request is performed by two callbacksonChangeValue(value)
andonChangeTool(tool)
. This demo apply the same pattern of an<input>
tag (React Controlled Components). - Redux - This advanced project show a scenario in which a redux store handle the state. Each component can dispatch a Redux action and edit the current view of the viewer.
- Bower - This project show how to use this component by mean of bower.
React SVG Pan Zoom requires the properties width
and height
to be set in order to work properly. If you need an autosized component you can use ReactDimension to get the dimensions of a wrapper element and pass them as properties to its child element.
git clone https://github.com/chrvadala/react-svg-pan-zoom.git
cd react-svg-pan-zoom
npm install && npm start
- v2.0 - Project refactor. Follow this guide for migration instructions.
- v2.1 - Adds
setPointOnViewerCenter
,reset
methods andclassName
,style
props - v2.2 - Introduce tool
auto
, improve default toolbar - v2.3 - Adds touch events support
- v2.4 - Adds es:next support, deploy new website
- v2.5 - Adds
preventPanOutside
andscaleFactor
props - v2.6 - Introduce transformation-matrix that reduce bundle size thanks to three shaking, Fix pan limit behaviour, Replaces toolbar links with buttons, minor improvements
Your contributions (issues and pull request) are very appreciated!
MIT