react-grid-panzoom

A React grid layout with built-in pan and zoom, drag-and-drop, and resizing. Think of it as a canvas-style grid - position elements on rows/columns, then let users pan, zoom, drag, and resize them.

Demo

• https://codesandbox.io/p/sandbox/hardcore-leavitt-mv3wrg
• https://codesandbox.io/p/sandbox/xenodochial-ride-l2jc5h
• https://codesandbox.io/p/sandbox/stupefied-euclid-xwkjl8

Installation

npm install react-grid-panzoom

Quick start

import Grid, { GridElement } from 'react-grid-panzoom';

const initialElements: GridElement[] = [
  { id: 1, x: 0, y: 0, w: 2, h: 1, render: () => <div>Element 1</div> },
  { id: 2, x: 2, y: 0, w: 1, h: 1, render: () => <div>Element 2</div> },
];

const Example = () => {
  const [elements, setElements] = useState(initialElements);

  return (
    <Grid
      cols={4}
      rows="auto"
      rowHeight={80}
      elements={elements}
      setElements={setElements}
    />
  );
};

Table of contents

• Grid props
• Element props
• Grid API (ref)
• Types

Grid props

Name	Type	Default	Description
autoOrganizeElements	boolean	false	Automatically re-run organizeGridElements (collision resolution / compacting) whenever elements change.
boundary	boolean	false	Allow moving the grid outside its container.
cols	number		Number of columns in the grid.
disabledMove	boolean	false	Disable moving (panning) the grid.
disabledScrollHorizontal	boolean	false	Disable horizontal scrolling of the grid.
disabledScrollVertical	boolean	false	Disable vertical scrolling of the grid.
disabledZoom	boolean	false	Disable zooming the grid.
elements	GridElement[]	[]	Grid elements. See Element props.
elementResizerWidth	number	15	Width (in pixels) of the resizer handle on resizable elements.
gapHorizontal	number		Horizontal gap between columns.
gapVertical	number		Vertical gap between rows.
helpLines	boolean	false	Display grid guide lines - useful with multiple columns/rows.
onContainerChange	func		Called when the grid is moved or zoomed.
onContainerClick	func		Called when the grid container is clicked (fires on mousedown/touchstart, same as onContainerPressStart).
onContainerPressStart	func		Called when the mouse/touch is pressed down on the grid container.
onContainerPressEnd	func		Called when the mouse/touch is released after being pressed on the grid container.
onContainerContextMenu	func		Called when the grid container's context menu is opened.
onElementClick	func		Called when an element is clicked: (element, { e, stop }) => void.
onElementContextMenu	func		Called when an element's context menu is opened (right click).
onElementsMeasureUpdate	func		Called when elements' heights are recalculated. Useful for elements with h: 'auto'.
onElementStartResizing	func		Called when an element starts resizing.
organizeGridElements	func		Custom function to organize/compact elements in the grid.
paddingLeft	number		Grid left padding.
paddingRight	number		Grid right padding.
ref	React.MutableRefObject<GridAPI>		Attach the Grid API to a ref.
rowHeight	number		Height of each row.
rows	number | 'auto'		Number of rows in the grid. Use 'auto' to let the grid expand automatically.
scrollSpeed	number		Scroll speed multiplier.
setElements	func		(elements, { type }) => void - called to update elements in the grid. type is 'programmatic' or 'user' depending on the source of the change.
width	number		Grid width.
zoomInitial	number		Initial zoom level.
zoomMax	number		Maximum zoom level.
zoomMin	number		Minimum zoom level.
zoomPosition	{ x?: number | 'center', y?: number | 'center' } | null		Position to zoom towards.
zoomSpeed	number		Zoom speed multiplier.

Element props

Each entry in elements supports:

Name	Type	Default	Description
id	string | number		Element id.
family	string		Id of the elements family this element belongs to.
followers	Array<string | number>		Ids of other elements that should move together with this one when it's dragged.
fullHeight	boolean	true	Expand the element to the full height of its container.
x	number		X position in the grid.
y	number		Y position in the grid.
w	number	1	Width in grid columns.
h	number | 'auto'	1	Height in grid rows. Use 'auto' to have it calculated automatically from content (rounded up).
render	func		Render function for the element: (element?) => JSX.Element.
resizable	boolean	true	Whether the element can be resized horizontally.
resizableVertical	boolean	false	Whether the element can be resized vertically.
disabled	boolean	false	Disable the element (no drag, no resize).
disabledMove	boolean	false	Disable moving the element in any direction.
disabledMoveHorizontal	boolean	false	Disable moving the element horizontally.
disabledMoveVertical	boolean	false	Disable moving the element vertically.
draggableSelector	string		Restrict dragging to clicks inside a matching selector (e.g. a drag handle).

Grid API (ref)

Attach a ref to Grid to access the imperative API:

const gridRef = useRef<GridAPI>(null);

<Grid ref={gridRef} ... />;

Method	Description
calculateCellPositionByPixels(x, y)	Converts a pixel position into a grid cell { x, y } position.
getLowestElementBottomInPixels()	Returns the bottom position (in pixels) of the lowest element in the grid.
getPanZoom()	Returns the underlying react-panzoom API instance.
grabElement(elementId, position?)	Programmatically grabs an element, optionally at a given position.
measureElementHeight(elementId)	Measures the current height (in rows) of a single element.
measureElementsHeight()	Measures the current heights (in rows) of all elements.
getElementsPaddingBottom()	Returns bottom padding per element, keyed by element id.
organizeElements(selectedElements?, options?)	Runs the organize/compact algorithm and returns the resulting elements.

Types

The package ships its own TypeScript types, exported from the package root:

import type {
  GridProps,
  GridElement,
  GridAPI,
  SetElements,
  OrganizeGridElements,
  OrganizeGridElementsProps,
  Position,
} from 'react-grid-panzoom';

License

MIT