React-Grid-Layout v2: Drag, Resize, and Responsive Grids for React

What React-Grid-Layout Does and Who It Targets

React-Grid-Layout is a grid layout system for React that gives users the ability to drag panels to new positions and resize them by pulling their edges. Unlike static CSS grid, it tracks each item's column position, row position, width, and height in JavaScript state, making every layout programmable and persistable to a database or localStorage.

The library targets developers building dashboards, analytics tools, trading interfaces, and any product where individual users arrange widgets to match their workflow. The README cites production usage on the trading platform BitMEX as a concrete example. The library is React-only, as the README states it does not require jQuery, and it publishes under the MIT license.

Responsive behavior is built in rather than bolted on. Breakpoint layouts can either be provided explicitly by the developer or autogenerated by the library from a single layout. The library monitors the container width and swaps the active layout when the viewport crosses a breakpoint threshold.

Version 2 Architecture: Four Entry Points and Composable Configuration

Version 2 is a complete TypeScript rewrite with a modernized API. The package ships four distinct entry points that split responsibilities cleanly.

The main entry react-grid-layout contains the React components and the v2 hooks. The entry react-grid-layout/core exports pure layout algorithms with no React dependency, making them suitable for custom renderers or server-side layout computations. The entry react-grid-layout/legacy provides 100% runtime API compatibility with v1, requiring no component rewrites. The entry react-grid-layout/extras ships optional pieces such as the GridBackground component.

Configuration in v2 groups related props into focused objects. The gridConfig object takes cols, rowHeight, margin, and padding. The dragConfig object takes enabled, handle, cancel, and bounded. The resizeConfig object takes enabled and handles. The compactor prop accepts the built-in verticalCompactor or any custom object that implements the Compactor interface. Position strategy is controlled separately through the positionStrategy prop, which chooses between CSS transform and absolute positioning.

This structure exists specifically to enable tree-shaking: the README notes that the modular architecture allows importing only what the application needs. The UMD bundle has been removed, so any project that previously loaded react-grid-layout via a script tag must migrate to a bundler such as Vite, webpack, or esbuild.

Setting Up a Grid with the v2 Hooks API

The package is available on npm as react-grid-layout. After installing, the CSS file at react-grid-layout/css/styles.css must be imported to get the default drag and resize handles. The v2 README gives this full component setup as its primary usage example:

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

The useContainerWidth hook measures the container div and returns the pixel width needed by the grid. The mounted flag prevents the grid from rendering before the measurement is available, which avoids a layout flash on first paint. The layout prop is an array of objects describing each item's column position, row position, width, and height. The gridConfig object here defines a 12-column grid with 30 pixels per row. Setting the handle class on dragConfig means only an element with class .handle triggers a drag, leaving the rest of the panel's content area interactive.

How Drag, Resize, and Compaction Operate Internally

When a user drags an item, react-grid-layout updates a local copy of the layout array and fires the onLayoutChange callback with the new positions. In v2, callback parameters are read-only: the README states that mutation of callback arguments is no longer permitted. Layout changes must be applied by updating state through onLayoutChange or by using the provided constraints.

The onDragStart callback in v2 fires after a 3-pixel movement threshold rather than on mousedown, as noted in the breaking changes section of the v2 RFC. This prevents unintended drag triggers on click events. Developers needing immediate mousedown response should listen to the standard onMouseDown event directly.

Compaction controls how the grid fills empty cells after a drag. The verticalCompactor, available as a built-in, packs items upward so no gaps appear below moved items. The compactor prop is pluggable: any object that implements the Compactor interface can replace the built-in algorithms. The previous verticalCompact boolean prop has been removed. Projects that previously set verticalCompact={false} should pass compactor={noCompactor} in v2.

Migrating a v1 Codebase to the Legacy Wrapper

The fastest migration path from v1 to v2 is a single import change. The README shows this one-line diff:

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

The README describes this as providing 100% runtime API compatibility with v1, meaning every prop, callback, and behavior from the previous version continues to work unchanged.

TypeScript users migrating from @types/react-grid-layout face additional naming changes. The README documents the mapping:

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

The legacy wrapper provides a migration runway without locking a codebase into the old API forever. The README migration table recommends the v2 API with hooks for any new project that needs custom compaction, SSR support (via the measureBeforeMount option), or better tree-shaking.

Limitations: Width Measurement, SSR, and Bundle Requirements

The width prop is now required in v2, a breaking change from v1 where WidthProvider handled measurement automatically. Every v2 application must supply a width, either from the useContainerWidth hook, from a resize observer of its own, or by passing a static value. Projects with complex server-side rendering pipelines must verify that their measurement strategy does not produce a mismatch between server and client renders. The README recommends setting measureBeforeMount: true for SSR use cases.

The UMD build that v1 shipped is gone entirely in v2. Any codebase loading the library from a CDN via a script tag cannot use v2 without adding a build step. The Makefile shows that the project itself uses Vite-based tools (tsup) and webpack for examples, confirming that a bundler is a hard requirement.

The library is also React-only. Applications built on Vue, Svelte, or other view layers cannot use it directly. For those environments, gridstack.js is a framework-agnostic alternative that manages grid layout in plain JavaScript and can be embedded into any component model.

Comparing React-Grid-Layout with gridstack.js and dnd kit

gridstack.js is a grid layout library that works with plain HTML and any JavaScript framework, managing layout state itself and emitting events. React-Grid-Layout ties layout state directly to React component state and React lifecycle, which gives it tighter integration with React rendering but removes it from consideration for non-React projects.

dnd kit is a React drag-and-drop toolkit focused on pointer semantics, accessibility, and composable drag sensors. It does not ship grid collision detection, automatic compaction, or breakpoint management. A developer using dnd kit to build a dashboard grid must implement collision resolution and layout calculation themselves. React-Grid-Layout delivers those behaviors out of the box, at the cost of a more opinionated grid structure.

The choice reduces to this: for a React application that needs users to freely rearrange a dashboard of widgets across breakpoints, React-Grid-Layout handles the layout math. For a custom drag interaction that does not fit a fixed grid, dnd kit is more appropriate.

Editorial conclusion

React-Grid-Layout suits any React application where users must rearrange, resize, or persist a set of panels, such as dashboards, analytics interfaces, or report builders. Teams on v1 can adopt the react-grid-layout/legacy import without touching a single component. Projects starting fresh should use the v2 API, verify that useContainerWidth fits their measurement strategy, and confirm that dropping the UMD build does not conflict with their deployment pipeline.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes