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.

!BitMEX UI

> 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, and useResponsiveLayout hooks
• Composable Configuration - Group related props into focused interfaces:

• Modular architecture - Import only what you need:

• 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

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

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 `

bash
npm install react-grid-layout

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

html

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

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
        
      )}
    
  );
}

The width prop is required. You have several options:

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

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

  return (
    
      {mounted && ...}
    
  );
}

tsx
...

For backwards compatibility, you can still use WidthProvider:

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

const GridLayoutWithWidth = WidthProvider(ReactGridLayout);

function MyGrid() {
  return ...;
}

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

• 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

…

Collapse