react-grid-layout

React Grid Layout is a grid layout system for React that lets users drag, resize, and rearrange widgets on a responsive canvas. It powers dashboards and drag-and-drop editors at companies like Grafana, Metabase, Kibana, and BitMEX, offering breakpoint-aware layouts, bounds checking, and serializable state without any jQuery dependency.

Version 2 is a complete TypeScript rewrite with first-class types, React hooks (useContainerWidth, useGridLayout, useResponsiveLayout), a tree-shakeable modular architecture, and a framework-agnostic core of pure layout algorithms. A legacy entry point preserves 100% runtime compatibility with the widely used v1 flat-props API.

What You Get

• A drop-in <ReactGridLayout> component that turns child elements into draggable, resizable grid widgets
• Responsive breakpoint support with independent layouts per breakpoint and auto-generated fallbacks
• React hooks (useContainerWidth, useGridLayout, useResponsiveLayout) for width measurement and layout state
• A framework-agnostic /core module exposing pure collision, compaction, and positioning algorithms
• A /legacy entry point giving 100% runtime compatibility with the v1 flat-props API for painless migration

Common Use Cases

• Building customizable, user-rearrangeable analytics dashboards
• Creating drag-and-drop page or form builders
• Persisting and restoring per-user widget layouts across sessions and screen sizes
• Composing responsive widget grids that reflow across breakpoints

Under The Hood

Architecture

The library is organized into layered modules under src/: a pure, React-free core/ (collision.ts, compactors.ts, constraints.ts, layout.ts, position.ts, calculate.ts, responsive.ts) that implements collision detection, compaction, and grid-cell math; a react/ layer with the GridLayout, ResponsiveGridLayout, GridItem, and WidthProvider components plus hooks; an extras/ module for optional pieces like GridBackground and fast O(n log n) compactors; and a legacy/ wrapper reproducing the v1 flat-props surface. Grid items are positioned with CSS transforms (or absolute positioning via a pluggable position strategy), and dragging/resizing is delegated to react-draggable and react-resizable.

Tech Stack

Written in TypeScript (57%) with remaining JavaScript, built with tsup into tree-shakeable ESM and CJS bundles with generated .d.ts types. Runtime dependencies are minimal: clsx, fast-equals, prop-types, react-draggable, react-resizable, and resize-observer-polyfill. React >= 16.3 is a peer dependency, with v2 targeting React 18+. Tooling includes Babel, Jest, ESLint (flat config), Prettier, Husky, and webpack for the examples site.

Code Quality

The repository has an extensive Jest test suite under test/spec/ covering compactors, constraints, core functions, hooks, lifecycle, drop alignment, margin consistency, TypeScript component typing, and backward compatibility, plus benchmark tests. Code is strongly typed with a clean separation between pure algorithms and React bindings, and exported surfaces are deliberately curated (some internal helpers are intentionally not exported). This is a mature, well-tested codebase.

API Design The v2 API groups related props into focused config objects (gridConfig, dragConfig, resizeConfig, positionStrategy, compactor) rather than a flat prop soup, and pairs them with ergonomic hooks so container width and layout state are easy to wire up. Documentation is thorough: a large README with 20+ live demos, a migration guide, an RFC, and a CodeSandbox. The legacy wrapper lowers migration cost significantly. The main tradeoff is that the required width prop and breakpoint concepts impose a modest learning curve for newcomers.