React-Grid-Layout [ ]() React-Grid-Layout is a grid layout system much like Packery or Gridster, for React. Unlike those systems, it is responsive and supports breakpoints. Breakpoint layouts can be provided…
React-Grid-Layout

![npm downloads]()
React-Grid-Layout is a grid layout system much like Packery or
Gridster, for React.
Unlike those systems, it is responsive and supports breakpoints. Breakpoint layouts can be provided by the user
or autogenerated.
RGL is React-only and does not require jQuery.
> GIF from production usage on BitMEX.com
[Demo | [Changelog](/CHANGELOG.md) | CodeSandbox Editable demo]
Table of Contents
- [What's New in v2](#whats-new-in-v2)
- [Migrating from v1](#migrating-from-v1)
- [Demos](#demos)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Responsive Usage](#responsive-usage)
- [Providing Grid Width](#providing-grid-width)
- [Hooks API](#hooks-api)
- [API Reference](#api-reference)
- [Extending: Custom Compactors & Position Strategies](#extending-custom-compactors--position-strategies)
- [Extras](#extras)
- [Performance](#performance)
- [Contribute](#contribute)
What's New in v2
Version 2 is a complete TypeScript rewrite with a modernized API:
- Full TypeScript support - First-class types, no more
@types/react-grid-layout - React Hooks - New
useContainerWidth,useGridLayout, anduseResponsiveLayouthooks - Composable Configuration - Group related props into focused interfaces:
gridConfig - cols, rowHeight, margin, padding
- dragConfig - enable, handle, cancel, bounded
- resizeConfig - enable, handles
- positionStrategy - transform vs absolute positioning
- compactor - vertical, horizontal, or custom algorithms
- Modular architecture - Import only what you need:
react-grid-layout - React components and hooks (v2 API)
- react-grid-layout/core - Pure layout algorithms (framework-agnostic)
- react-grid-layout/legacy - v1 flat props API for migration
- react-grid-layout/extras - Optional components like GridBackground
- Smaller bundle - Tree-shakeable ESM and CJS builds
Breaking Changes
See the [RFC](./rfcs/0001-v2-typescript-rewrite.md#breaking-changes-in-v2) for detailed migration examples.
| Change | Description |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [width prop required](./rfcs/0001-v2-typescript-rewrite.md#breaking-changes-in-v2) | Use useContainerWidth hook or provide your own measurement |
| [onDragStart threshold](./rfcs/0001-v2-typescript-rewrite.md#1-ondragstart-no-longer-fires-on-click-only-events) | Now fires after 3px movement, not on mousedown. Use onMouseDown for immediate response |
| [Immutable callbacks](./rfcs/0001-v2-typescript-rewrite.md#2-immutable-callback-parameters) | Callback parameters are read-only. Use onLayoutChange or constraints instead of mutation |
| [data-grid in legacy only](./rfcs/0001-v2-typescript-rewrite.md#3-data-grid-prop-only-available-in-legacy-wrapper) | v2 requires explicit layout prop. Use legacy wrapper for data-grid |
| [Pluggable compaction](./rfcs/0001-v2-typescript-rewrite.md#4-pluggable-compaction-algorithms) | Compaction is now pluggable via Compactor interface. Optional fast O(n log n) algorithm in /extras |
| UMD bundle removed | Use a bundler (Vite, webpack, esbuild) |
| verticalCompact removed | Use compactType={null} or compactor={noCompactor} |
Migrating from v1
Quick migration - change your import to use the legacy wrapper:
diff
- import GridLayout, { Responsive, WidthProvider } from 'react-grid-layout';
+ import GridLayout, { Responsive, WidthProvider } from 'react-grid-layout/legacy';
This provides 100% runtime API compatibility with v1.
TypeScript users: If you were using @types/react-grid-layout, note that v2 includes its own types with some naming changes:
| Old (@types/react-grid-layout) | New (v2) | Notes |
| -------------------------------- | ------------------- | ----------------------- |
| RGL.Layout | LayoutItem | Single grid item |
| RGL.Layout[] | Layout | Array of items |
| RGL.Layouts | ResponsiveLayouts | Breakpoint → layout map |
diff
- import RGL from 'react-grid-layout';
- const item: RGL.Layout = { i: 'a', x: 0, y: 0, w: 1, h: 1 };
- const layouts: RGL.Layouts = { lg: [item] };
+ import { LayoutItem, ResponsiveLayouts } from 'react-grid-layout/legacy';
+ const item: LayoutItem = { i: 'a', x: 0, y: 0, w: 1, h: 1 };
+ const layouts: ResponsiveLayouts = { lg: [item] };
Full migration - adopt the v2 API for new features and better tree-shaking:
typescript
import ReactGridLayout, { useContainerWidth, verticalCompactor } from 'react-grid-layout';
function MyGrid() {
const { width, containerRef, mounted } = useContainerWidth();
return (
{mounted && (
{children}
)}
);
}
| Use Case | Recommendation |
| -------------------- | ---------------------------------- |
| Existing v1 codebase | react-grid-layout/legacy |
| New project | v2 API with hooks |
| Custom compaction | v2 with custom Compactor |
| SSR | v2 with measureBeforeMount: true |
Demos
1. Showcase
1. Basic
1. No Dragging/Resizing (Layout Only)
1. Messy Layout Autocorrect
1. Layout Defined on Children
1. Static Elements
1. Adding/Removing Elements
1. Saving Layout to LocalStorage
1. Saving a Responsive Layout to LocalStorage
1. Minimum and Maximum Width/Height
1. Dynamic Minimum and Maximum Width/Height
1. Toolbox
1. Drag From Outside
1. Bounded Layout
1. Responsive Bootstrap-style Layout
1. Scaled Containers
1. Allow Overlap
1. All Resizable Handles
1. Compactor Showcase
1. Pluggable Constraints
1. Aspect Ratio Constraints
1. Custom Constraints
Projects Using React-Grid-Layout
_Know of others? Create a PR to let me know!_Features
- 100% React - no jQuery
- Full TypeScript support
- Compatible with server-rendered apps
- Draggable widgets
- Resizable widgets
- Static widgets
- Configurable packing: horizontal, vertical, or off
- Bounds checking for dragging and resizing
- Widgets may be added or removed without rebuilding grid
- Layout can be serialized and restored
- Responsive breakpoints
- Separate layouts per responsive breakpoint
- Grid Items placed using CSS Transforms
- Compatibility with `
Installation
bash
npm install react-grid-layout
Include the stylesheets in your application:
js
import "react-grid-layout/css/styles.css";
import "react-resizable/css/styles.css";
Or link them directly:
html
Quick Start
tsx
import ReactGridLayout, { useContainerWidth } from "react-grid-layout";
import "react-grid-layout/css/styles.css";
import "react-resizable/css/styles.css";
function MyGrid() {
const { width, containerRef, mounted } = useContainerWidth();
const layout = [
{ i: "a", x: 0, y: 0, w: 1, h: 2, static: true },
{ i: "b", x: 1, y: 0, w: 3, h: 2, minW: 2, maxW: 4 },
{ i: "c", x: 4, y: 0, w: 1, h: 2 }
];
return (
{mounted && (
a
b
c
)}
);
}
You can also define layout on children using data-grid:
tsx
a
b
c
Responsive Usage
Use Responsive for automatic breakpoint handling:
tsx
import { Responsive, useContainerWidth } from "react-grid-layout";
function MyResponsiveGrid() {
const { width, containerRef, mounted } = useContainerWidth();
const layouts = {
lg: [{ i: "1", x: 0, y: 0, w: 2, h: 2 }],
md: [{ i: "1", x: 0, y: 0, w: 2, h: 2 }]
};
return (
{mounted && (
1
2
3
)}
);
}
Providing Grid Width
The width prop is required. You have several options:
Option 1: useContainerWidth Hook (Recommended)
tsx
import ReactGridLayout, { useContainerWidth } from "react-grid-layout";
function MyGrid() {
const { width, containerRef, mounted } = useContainerWidth();
return (
{mounted && ...}
);
}
Option 2: Fixed Width
tsx
...
Option 3: CSS Container Queries or ResizeObserver
Use any width measurement library like react-sizeme or your own ResizeObserver implementation.
Option 4: Legacy WidthProvider HOC
For backwards compatibility, you can still use WidthProvider:
tsx
import ReactGridLayout, { WidthProvider } from "react-grid-layout/legacy";
const GridLayoutWithWidth = WidthProvider(ReactGridLayout);
function MyGrid() {
return ...;
}
Hooks API
The v2 API provides three hooks for different use cases. Choose based on your needs:
| Hook | Use When |
| --------------------- | -------------------------------------------------------------------- |
| useContainerWidth | You need responsive width measurement (most common) |useGridLayout
| | You're building a custom grid component or need direct state control |useResponsiveLayout
| | You're building a custom responsive grid with breakpoint logic |
useContainerWidth
Observes container width using ResizeObserver and provides reactive width updates. This is the recommended way to provide width to the grid.
Why use it instead of WidthProvider?
- Hooks are more composable and easier to test
- No HOC wrapper means simpler component tree
- Explicit control over when to render (via mounted`)
- Works better with SSR
tsx
import { useContainerWidth } from "react-grid-layout";
function MyGrid() {
const { width, containerRef, mounted, measureWidth } = useContainerWidth({
measureBeforeMount: false, // Set true for SSR
initialWidth: 1280 // Width before first measurement
});
return (
{mounted && }
);
}
Type Definitions:
ts
interface UseContainerWidthOptions {
/** Delay render until width is measured. Useful for SSR. Default: false */
measureBeforeMount?: boolean;
/** Initial width before measurement. Default: 1280 */
initialWidth?: number;
}
interface UseContainerWidthResult {
/** Current container width in pixels */
width: number;
/** Whether the container has been measured at least once */
mounted: boolean;
/** Ref to attach to the container element */
containerRef: RefObject;
/** Manually trigger a width measurement */
measureWidth: () => void;
}
useGridLayout
Core layout state management hook. Use this when you need direct cont
…
-
react-grid-layout
A draggable and resizable grid layout with responsive breakpoints, for React.
TypeScript ★ 22k 2mo agoExplain → -
react-draggable
React draggable component
JavaScript ★ 9.3k 2d agoExplain → -
react-resizable
A simple React component that is resizable with a handle.
TypeScript ★ 2.6k 2d agoExplain →
No repos match these filters.