Guide · Open source

How to use react-grid-layout: install, set up a grid and go responsive

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

react-grid-layout is a React library for building grids where items can be dragged and resized, with support for responsive breakpoints. This guide explains what it does, how to install it with npm, and how to set up a layout that changes with screen width. It also covers the main differences in the v2 API so you can avoid common migration problems.

React-Grid-Layoutreact-grid-layout/react-grid-layout · ★ 22.5k · MIT Install options & downloads

Quick start

1Install the package. Run npm install react-grid-layout in a project that already has React and Node.js.
2Decide on v2 or legacy. Use the v2 API for new projects. Use react-grid-layout/legacy if you are migrating an existing v1 codebase.
3Measure the container. Call useContainerWidth to get width, containerRef and mounted, since v2 requires a width prop.
4Render the grid. Pass width, layout and gridConfig to the grid component and render your items as children.
5Configure drag and resize. Set dragConfig and resizeConfig to control which behaviours are enabled and which handles are used.
6Add breakpoints if needed. Provide a layout for each breakpoint or let the library autogenerate them, then check the Responsive Usage section of the README.

What react-grid-layout does

React-Grid-Layout is a grid layout system similar in purpose to Packery or Gridster. Unlike those systems, it is responsive and supports breakpoints, and the breakpoint layouts can either be provided by you or generated automatically.

It is React-only and does not require jQuery.

Drag and resize items within a grid
Responsive breakpoints with different arrangements at different widths
Layouts you supply or autogenerated breakpoint layouts
TypeScript types included

Install react-grid-layout with npm

You need Node.js and an npm-compatible package manager, plus React in your project. Install the library from npm with the command below.

npm install react-grid-layout

Choose the v2 API or the legacy wrapper

Version 2 is a TypeScript rewrite with hooks and grouped configuration props such as gridConfig, dragConfig, resizeConfig and compactor. Version 2 requires a width prop, so you measure the container, for example with the useContainerWidth hook.

If you are migrating from v1, you can change your import to the legacy wrapper, which the README says provides 100% runtime API compatibility with v1. For new projects, the README recommends the v2 API with hooks.

Existing v1 codebase: import from react-grid-layout/legacy
New project: use the v2 API with hooks
Custom compaction: v2 with a custom Compactor
Server-side rendering: v2 with measureBeforeMount: true

- import GridLayout, { Responsive, WidthProvider } from 'react-grid-layout';
+ import GridLayout, { Responsive, WidthProvider } from 'react-grid-layout/legacy';

Build a basic grid with the v2 API

Measure the container width with useContainerWidth, render the grid only after it has mounted, and pass the layout along with your grid settings. The example below comes from the README migration section; replace layout and children with your own data and elements.

gridConfig sets cols and rowHeight
dragConfig sets enabled and an optional handle selector
compactor accepts verticalCompactor

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

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

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

Understand the breaking changes in v2

Several v2 changes can break existing code. Check this list before upgrading an app built on v1.

The width prop is required. Use the useContainerWidth hook or your own measurement.
onDragStart now fires after 3px of movement, not on mousedown. Use onMouseDown for an immediate response.
Callback parameters are read-only. Use onLayoutChange or constraints instead of mutating values.
The data-grid prop is only available in the legacy wrapper. v2 requires an explicit layout prop.
verticalCompact is removed. Use compactType={null} or compactor={noCompactor}.
The UMD bundle is removed. Use a bundler such as Vite, webpack or esbuild.

Explore the demos and advanced options

The README lists demos covering saving layouts to LocalStorage, static elements, bounded layouts, dragging from outside the grid, allowing overlap and minimum and maximum sizes. Reading the example source is a practical way to see how these options are wired up.

The README also describes an extras entry point with optional components such as GridBackground, and a core entry point with framework-agnostic layout algorithms.

react-grid-layout/core for pure layout algorithms
react-grid-layout/extras for optional components like GridBackground
Demos are linked from the project README

What people use it for

A dashboard where users move and resize panels
A responsive page that uses different arrangements at different screen widths
A layout editor where users save their arrangement to LocalStorage, as shown in the demos
A toolbox that lets users drag new items into a grid, as shown in the demos

Frequently asked questions

How do I install react-grid-layout?

Run npm install react-grid-layout in a project that has Node.js, an npm-compatible package manager and React installed. The README gives this as the install method.

Is react-grid-layout free to use?

The project is licensed under MIT, according to the project information. Check the LICENSE file in the repository for the full terms.

Does react-grid-layout work without React?

No. The library is React-only. For non-React projects, the README points to other options such as Gridster or Packery, which are similar in purpose.

Does react-grid-layout need jQuery?

No. The README states that RGL is React-only and does not require jQuery.

Why does my grid not render in react-grid-layout v2?

v2 requires a width prop. Measure the container with useContainerWidth and render the grid only after mounted is true, as in the README example.

How is react-grid-layout different from CSS grid?

A plain CSS grid is likely enough for a static layout. react-grid-layout is for layouts where users drag and resize items and where arrangements change across breakpoints.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use react-grid-layout if you build React dashboards with movable, resizable panels or need different layouts at different screen widths. Pick plain CSS grid for static layouts, or a non-React library such as Gridster or Packery if your project is not built on React.

Install options & downloads