{"id":11713,"library":"react-grid-layout","title":"React Grid Layout (RGL)","description":"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.","status":"active","version":"2.2.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/STRML/react-grid-layout","tags":["javascript","react","grid","drag","draggable","resize","resizable","fluid","responsive","typescript"],"install":[{"cmd":"npm install react-grid-layout","lang":"bash","label":"npm"},{"cmd":"yarn add react-grid-layout","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-grid-layout","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for all React components.","package":"react","optional":false},{"reason":"Peer dependency for rendering React components.","package":"react-dom","optional":false}],"imports":[{"note":"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.","wrong":"import Responsive from 'react-grid-layout';","symbol":"Responsive","correct":"import { Responsive, WidthProvider } from 'react-grid-layout';"},{"note":"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.","wrong":"import { Layout as RGL_Layout } from 'react-grid-layout/legacy';","symbol":"Layout","correct":"import { Layout } from 'react-grid-layout';"},{"note":"Introduced in v2, these hooks (like `useResponsiveLayout`, `useGridLayout`, `useContainerWidth`) offer a more granular, hooks-based API. They are typically imported from the `/hooks` subpath.","wrong":"import { useResponsiveLayout } from 'react-grid-layout';","symbol":"useResponsiveLayout","correct":"import { useResponsiveLayout } from 'react-grid-layout/hooks';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport { Responsive, WidthProvider, Layout } from 'react-grid-layout';\nimport 'react-grid-layout/css/styles.css';\nimport 'react-resizable/css/styles.css';\n\n// WidthProvider is a HOC that provides the width prop to the Responsive grid.\nconst ResponsiveGridLayout = WidthProvider(Responsive);\n\nconst MyResponsiveDashboard: React.FC = () => {\n  const [currentLayout, setCurrentLayout] = useState<Layout[]>([\n    { i: 'a', x: 0, y: 0, w: 1, h: 2 },\n    { i: 'b', x: 1, y: 0, w: 3, h: 2, minW: 2, maxW: 4 },\n    { i: 'c', x: 4, y: 0, w: 1, h: 2 }\n  ]);\n\n  // Define responsive breakpoints and column counts\n  const breakpoints = { lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 };\n  const cols = { lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 };\n\n  const onLayoutChange = (layout: Layout[], layouts: { [key: string]: Layout[] }) => {\n    // Save the current layout state, e.g., to local storage or a backend\n    console.log('Layout changed:', layout);\n    setCurrentLayout(layout);\n  };\n\n  return (\n    <div style={{ padding: '20px' }}>\n      <h1>My Responsive Dashboard</h1>\n      <ResponsiveGridLayout\n        className=\"layout\"\n        layouts={{ lg: currentLayout }} // Provide current layout for the 'lg' breakpoint\n        breakpoints={breakpoints}\n        cols={cols}\n        rowHeight={30}\n        onLayoutChange={onLayoutChange}\n        isDraggable={true}\n        isResizable={true}\n        margin={[10, 10]}\n        containerPadding={[10, 10]}\n        measureBeforeMount={true} // Set to true for initial measurement if not using SSR\n      >\n        <div key=\"a\" style={{ background: '#e0f7fa', border: '1px solid #b2ebf2', padding: '10px' }}>Widget A</div>\n        <div key=\"b\" style={{ background: '#e8f5e9', border: '1px solid #c8e6c9', padding: '10px' }}>Widget B</div>\n        <div key=\"c\" style={{ background: '#fff3e0', border: '1px solid #ffe0b2', padding: '10px' }}>Widget C</div>\n      </ResponsiveGridLayout>\n    </div>\n  );\n};\n\nexport default MyResponsiveDashboard;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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`).","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure the `width` prop is passed to `ReactGridLayout`, or wrap it with `WidthProvider` if using `Responsive`.","message":"Since 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If immediate feedback on mouse down is required, use a standard `onMouseDown` event handler on your grid items instead of `onDragStart`.","message":"The `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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Callback 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Version 2.2.0 contained a critical layout bug that could lead to incorrect grid positioning and behavior. It was quickly patched in subsequent releases.","severity":"gotcha","affected_versions":"2.2.0"},{"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.","message":"Older 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.","severity":"gotcha","affected_versions":"<2.2.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"When using `ReactGridLayout` directly, you must explicitly pass a `width` prop. If using `Responsive`, ensure it's wrapped with `WidthProvider`.","cause":"Using `ReactGridLayout` directly (without `WidthProvider`) in v2.0.0+ without providing a `width` prop.","error":"Error: \"React-Grid-Layout: The width property is required!\""},{"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.","cause":"The `layout` prop (or `layouts` for `Responsive`) is not an array of valid layout objects, or is `undefined`.","error":"TypeError: Cannot read properties of undefined (reading 'map') at getLayoutItem"},{"fix":"Upgrade to `react-grid-layout@2.2.3` or a later version. The library now defers state updates to prevent this error.","cause":"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.","error":"ResizeObserver loop limit exceeded"},{"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.","cause":"Attempting to use CommonJS `require()` syntax (`const RGL = require('react-grid-layout');`) in a modern ESM-only project context.","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm"}