Registry / web-framework / react-grid-layout

react-grid-layout

JSON →
library2.2.3jsnpmunverified

React-Grid-Layout (RGL) is a powerful and flexible grid layout system for React applications, enabling draggable and resizable components with responsive breakpoint support. Unlike older solutions like Packery or Gridster, RGL is built purely with React, avoiding external dependencies such as jQuery. The current stable version is 2.2.3, with frequent patch releases addressing bugs and minor enhancements. Version 2.0.0 marked a significant rewrite, introducing a full TypeScript codebase and a modernized Hooks-based API for improved composability and performance. Key differentiators include its robust responsive behavior, native React implementation, and first-class TypeScript support since version 2, making it suitable for complex, enterprise-grade dashboards and user interfaces. Releases occur frequently for bug fixes and minor features, typically multiple times per month for patch versions.

npm install react-grid-layout
INSTALL
IMPORT
SIG · REACT-GRID-LAYOUT
R
react-grid-layout
web-frameworkjavascriptv2.2.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Responsive
import { Responsive, WidthProvider } from 'react-grid-layout';
import Responsive from 'react-grid-layout';
The `Responsive` component is a named export and typically used with `WidthProvider` for automatic width detection. The non-responsive `ReactGridLayout` is also a named export but less commonly used.
Layout
import { Layout } from 'react-grid-layout';
import { Layout as RGL_Layout } from 'react-grid-layout/legacy';
This is the primary TypeScript type for layout items. Since v2, `@types/react-grid-layout` is no longer needed as types are shipped with the package.
useResponsiveLayout
import { useResponsiveLayout } from 'react-grid-layout/hooks';
import { useResponsiveLayout } from 'react-grid-layout';
Introduced in v2, these hooks (like `useResponsiveLayout`, `useGridLayout`, `useContainerWidth`) offer a more granular, hooks-based API. They are typically imported from the `/hooks` subpath.

This example demonstrates a basic responsive, draggable, and resizable grid layout using the `Responsive` component with `WidthProvider` and local state management for layout changes. It includes custom breakpoints and grid items.

import React, { useState } from 'react'; import { Responsive, WidthProvider, Layout } from 'react-grid-layout'; import 'react-grid-layout/css/styles.css'; import 'react-resizable/css/styles.css'; // WidthProvider is a HOC that provides the width prop to the Responsive grid. const ResponsiveGridLayout = WidthProvider(Responsive); const MyResponsiveDashboard: React.FC = () => { const [currentLayout, setCurrentLayout] = useState<Layout[]>([ { i: 'a', x: 0, y: 0, w: 1, h: 2 }, { i: 'b', x: 1, y: 0, w: 3, h: 2, minW: 2, maxW: 4 }, { i: 'c', x: 4, y: 0, w: 1, h: 2 } ]); // Define responsive breakpoints and column counts const breakpoints = { lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }; const cols = { lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }; const onLayoutChange = (layout: Layout[], layouts: { [key: string]: Layout[] }) => { // Save the current layout state, e.g., to local storage or a backend console.log('Layout changed:', layout); setCurrentLayout(layout); }; return ( <div style={{ padding: '20px' }}> <h1>My Responsive Dashboard</h1> <ResponsiveGridLayout className="layout" layouts={{ lg: currentLayout }} // Provide current layout for the 'lg' breakpoint breakpoints={breakpoints} cols={cols} rowHeight={30} onLayoutChange={onLayoutChange} isDraggable={true} isResizable={true} margin={[10, 10]} containerPadding={[10, 10]} measureBeforeMount={true} // Set to true for initial measurement if not using SSR > <div key="a" style={{ background: '#e0f7fa', border: '1px solid #b2ebf2', padding: '10px' }}>Widget A</div> <div key="b" style={{ background: '#e8f5e9', border: '1px solid #c8e6c9', padding: '10px' }}>Widget B</div> <div key="c" style={{ background: '#fff3e0', border: '1px solid #ffe0b2', padding: '10px' }}>Widget C</div> </ResponsiveGridLayout> </div> ); }; export default MyResponsiveDashboard;
Debug
Known issues
breakingVersion 2.0.0 introduced a complete TypeScript rewrite and a modernized Hooks API, breaking compatibility with v1's flat props API. Many props were grouped into config objects (e.g., `gridConfig`, `dragConfig`).
fix
Migrate to the new Hooks API and composable configuration objects. Refer to the official migration guide or RFC for v2. If a quick migration is needed, consider using `react-grid-layout/legacy` which provides a v1-compatible wrapper.
affects: >=2.0.0
breakingSince v2.0.0, the `width` prop is now explicitly required for `ReactGridLayout`. While `Responsive` components typically handle this via `WidthProvider`, direct usage of `ReactGridLayout` without `WidthProvider` will require manual width provisioning.
fix
Ensure the `width` prop is passed to `ReactGridLayout`, or wrap it with `WidthProvider` if using `Responsive`.
affects: >=2.0.0
breakingThe `onDragStart` callback in v2.0.0 now fires after a 3px movement threshold, rather than on `mousedown`. This prevents unintended drag events from simple clicks.
fix
If immediate feedback on mouse down is required, use a standard `onMouseDown` event handler on your grid items instead of `onDragStart`.
affects: >=2.0.0
breakingCallback parameters (e.g., in `onDrag`, `onResize`) are immutable in v2.0.0. Direct mutation of the layout array or individual layout items within these callbacks is no longer supported and can lead to unexpected behavior.
fix
Instead of mutating callback parameters, use the `onLayoutChange` callback to receive the new layout array and update your component's state accordingly. For custom constraints, use the new pluggable constraints system.
affects: >=2.0.0
gotchaVersion 2.2.0 contained a critical layout bug that could lead to incorrect grid positioning and behavior. It was quickly patched in subsequent releases.
fix
Do not use `react-grid-layout@2.2.0`. Upgrade to `2.2.1` or any later patch version (e.g., `2.2.3`) to avoid this bug.
affects: 2.2.0
gotchaOlder versions (pre-2.2.3) could encounter a 'ResizeObserver loop limit exceeded' error, particularly when rapidly resizing or dragging elements, due to state update timing.
fix
Upgrade to `react-grid-layout@2.2.3` or newer, as this issue was addressed by deferring state updates to prevent the infinite loop.
affects: <2.2.3
Errors
Common errors & fixes
Error: "React-Grid-Layout: The width property is required!"
Using `ReactGridLayout` directly (without `WidthProvider`) in v2.0.0+ without providing a `width` prop.
fix
When using `ReactGridLayout` directly, you must explicitly pass a `width` prop. If using `Responsive`, ensure it's wrapped with `WidthProvider`.
TypeError: Cannot read properties of undefined (reading 'map') at getLayoutItem
The `layout` prop (or `layouts` for `Responsive`) is not an array of valid layout objects, or is `undefined`.
fix
Ensure that the `layout` prop is an array where each item is an object with at least `i` (id), `x`, `y`, `w`, and `h` properties. Initialize it to an empty array (`[]`) if there are no items initially.
ResizeObserver loop limit exceeded
Rapid and frequent DOM mutations within the grid could trigger a ResizeObserver to report changes repeatedly, leading to an infinite loop. This was a known issue in versions prior to 2.2.3.
fix
Upgrade to `react-grid-layout@2.2.3` or a later version. The library now defers state updates to prevent this error.
ReferenceError: require is not defined in ES module scope
Attempting to use CommonJS `require()` syntax (`const RGL = require('react-grid-layout');`) in a modern ESM-only project context.
fix
Use ESM `import` statements (e.g., `import { Responsive } from 'react-grid-layout';`). Ensure your project's `package.json` specifies `"type": "module"` if you intend to use ESM exclusively, or configure your bundler (Webpack, Rollup, Vite) correctly.
Upgrade
Version history
2.2.3latest on npm
Audit
Dependencies
reactrequiredPeer dependency for all React components.
react-domrequiredPeer dependency for rendering React components.
Agent activity
2 hits · last 30 days
node
2
Resources