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 by the user or autogenerated.

RGL is React-only and does not require jQuery.

GIF from production usage on BitMEX.com

[Demo | Changelog | CodeSandbox Editable demo]

Table of Contents

• What's New in v2
• Migrating from v1
• Demos
• Features
• Installation
• Quick Start
• Responsive Usage
• Providing Grid Width
• Hooks API
• API Reference
• Extending: Custom Compactors & Position Strategies
• Extras
• Performance
• 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, and useResponsiveLayout hooks
• 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 for detailed migration examples.

Change	Description
width prop required	Use useContainerWidth hook or provide your own measurement
onDragStart threshold	Now fires after 3px movement, not on mousedown. Use onMouseDown for immediate response
Immutable callbacks	Callback parameters are read-only. Use onLayoutChange or constraints instead of mutation
data-grid in legacy only	v2 requires explicit layout prop. Use legacy wrapper for data-grid
Pluggable compaction	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:

- 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

- 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:

import ReactGridLayout, { useContainerWidth, verticalCompactor } from 'react-grid-layout';

function MyGrid() {
  const { width, containerRef, mounted } = useContainerWidth();

  return (



      {mounted && (
        <ReactGridLayout
          width={width}
          layout={layout}
          gridConfig={{ cols: 12, rowHeight: 30 }}
          dragConfig={{ enabled: true, handle: '.handle' }}
          compactor={verticalCompactor}
        >
          {children}
        </ReactGridLayout>
      )}



  );
}

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
2. Basic
3. No Dragging/Resizing (Layout Only)
4. Messy Layout Autocorrect
5. Layout Defined on Children
6. Static Elements
7. Adding/Removing Elements
8. Saving Layout to LocalStorage
9. Saving a Responsive Layout to LocalStorage
10. Minimum and Maximum Width/Height
11. Dynamic Minimum and Maximum Width/Height
12. Toolbox
13. Drag From Outside
14. Bounded Layout
15. Responsive Bootstrap-style Layout
16. Scaled Containers
17. Allow Overlap
18. All Resizable Handles
19. Compactor Showcase
20. Pluggable Constraints
21. Aspect Ratio Constraints
22. Custom Constraints

Projects Using React-Grid-Layout

• Basedash
• BitMEX
• AWS CloudFront Dashboards
• Grafana
• Metabase
• HubSpot
• Kibana
• Monday

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 <React.StrictMode>

Version	Compatibility
>= 2.0.0	React 18+, TypeScript
>= 0.17.0	React 16 & 17

Installation

npm install react-grid-layout

Include the stylesheets in your application:

import "react-grid-layout/css/styles.css";
import "react-resizable/css/styles.css";

Or link them directly:

<link rel="stylesheet" href="https://github.com/react-grid-layout/react-grid-layout/raw/2.2.3/node_modules/react-grid-layout/css/styles.css" />
<link rel="stylesheet" href="https://github.com/react-grid-layout/react-grid-layout/raw/2.2.3/node_modules/react-resizable/css/styles.css" />

Quick Start

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 && (
        <ReactGridLayout
          layout={layout}
          width={width}
          gridConfig={{ cols: 12, rowHeight: 30 }}
        >


a




b




c


        </ReactGridLayout>
      )}



  );
}

You can also define layout on children using data-grid:

<ReactGridLayout width={width} gridConfig={{ cols: 12, rowHeight: 30 }}>



    a






    b






    c



</ReactGridLayout>

Responsive Usage

Use Responsive for automatic breakpoint handling:

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 && (
        <Responsive
          layouts={layouts}
          breakpoints={{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }}
          cols={{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }}
          width={width}
        >


1




2




3


        </Responsive>
      )}



  );
}

Providing Grid Width

The width prop is required. You have several options:

Option 1: useContainerWidth Hook (Recommended)

import ReactGridLayout, { useContainerWidth } from "react-grid-layout";

function MyGrid() {
  const { width, containerRef, mounted } = useContainerWidth();

  return (



      {mounted && <ReactGridLayout width={width}>...</ReactGridLayout>}



  );
}

Option 2: Fixed Width

<ReactGridLayout width={1200}>...</ReactGridLayout>

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:

import ReactGridLayout, { WidthProvider } from "react-grid-layout/legacy";

const GridLayoutWithWidth = WidthProvider(ReactGridLayout);

function MyGrid() {
  return <GridLayoutWithWidth>...</GridLayoutWithWidth>;
}

Hooks API

The v2 API provides three hooks for di