react-grid-layout v2: A TypeScript rewrite with a split API for legacy and new projects

What problem it solves and who it is for

React-Grid-Layout solves the problem of arranging React components into a draggable and resizable grid, similar to Packery or Gridster but without jQuery. It targets developers building dashboards, admin panels, or any interface where users need to rearrange widgets. The library is React-only, which removes a dependency that older grid systems carried. The v2 rewrite specifically addresses TypeScript users, because v1 relied on separate @types packages with naming mismatches. It also targets teams that want smaller bundles: v2 is tree-shakeable with ESM and CJS builds. The split into react-grid-layout, react-grid-layout/core, react-grid-layout/legacy, and react-grid-layout/extras means you can import only the algorithms or components you need. This is a library for React developers who need interactive layouts, not for static page builders.

How the v2 architecture works

The v2 architecture separates pure layout algorithms from React components. The react-grid-layout/core entry point contains framework-agnostic logic, while the main package provides components and hooks. Configuration is grouped into focused interfaces: gridConfig handles cols, rowHeight, margin, and padding; dragConfig controls enable, handle, cancel, and bounded; resizeConfig covers enable and handles. Positioning is selected via positionStrategy, which can be transform or absolute. Compaction is pluggable through a Compactor interface, with a vertical compactor exported as verticalCompactor and an optional fast O(n log n) algorithm in /extras. The README shows a basic example where useContainerWidth measures the parent element and returns width, containerRef, and mounted. The grid renders only after mounted is true, which avoids a flash of zero width. This design means you can swap compaction strategies or position strategies without changing the component tree.

Getting it running: installation and quick start

The README does not give explicit install commands, but it references the npm package react-grid-layout and shows import paths. You would install it with your package manager, for example npm install react-grid-layout. The quick start example imports ReactGridLayout, useContainerWidth, and verticalCompactor from the main package. You create a component that calls useContainerWidth to get width and a ref, attach the ref to a div, and render ReactGridLayout only when mounted is true. The grid requires a layout prop, which is an array of items with i, x, y, w, and h. The gridConfig prop takes an object with cols and rowHeight. The dragConfig prop can set enabled and handle. For migration from v1, the README shows changing the import to react-grid-layout/legacy, which provides 100% runtime API compatibility. The legacy wrapper also keeps the data-grid prop for defining layout on children, which v2 does not support.

The v1 to v2 migration split and its consequences

The v2 release introduces a hard split between the legacy API and the new API. The legacy wrapper at react-grid-layout/legacy gives you the old flat props and data-grid behavior, so existing v1 code can move with a one-line import change. The new v2 API requires an explicit layout prop and does not support data-grid on children. That is a significant difference for teams that defined layout inline on each child. The README also lists breaking changes: the width prop is now required, so you must measure the container or use useContainerWidth. onDragStart now fires after 3px of movement, not on mousedown. Callback parameters are read-only, so you cannot mutate them. The verticalCompact prop is removed, replaced by compactType={null} or compactor={noCompactor}. The UMD bundle is gone, so you need a bundler. These changes mean migration is not automatic unless you use the legacy wrapper. For a new project, the v2 API is cleaner, but for an existing large codebase, the legacy path is the safer first step.

Performance and bundle size claims

The README claims smaller bundles due to tree-shakeable ESM and CJS builds, and the modular architecture lets you import only what you need. The core package contains pure layout algorithms, which could be used without React, potentially reducing bundle size in non-React contexts. The optional fast O(n log n) compactor in /extras is a performance feature, but the README does not give benchmark numbers. The useContainerWidth hook avoids rendering until the container is measured, which prevents layout jumps. However, the claim of smaller bundles depends on your bundler and how much you import. If you use the legacy wrapper, you likely get the full v1 behavior and lose some tree-shaking benefits. The README does not provide concrete bundle size figures, so you should measure with your own build. The architecture maps section is mentioned but not detailed in the truncated material, so performance tuning beyond these points is not documented here.

Limitations and where it is the wrong tool

The most obvious limitation is the required width prop in v2. Without a measured width, the grid cannot calculate positions correctly, and the README forces you to use useContainerWidth or your own measurement. This adds complexity for simple static grids. The removal of data-grid from v2 means you cannot define layout on children directly, which is a common pattern in v1. If you rely on onDragStart firing immediately on mousedown, v2 changes that behavior, which could break drag interactions that need instant feedback. The UMD bundle removal means no script-tag usage; you must use a bundler. For server-side rendering, the README suggests measureBeforeMount: true, but it does not explain the implications. The library is also not suitable for virtualized lists of thousands of items, as the README does not mention any virtualization support. If you need a grid that works without JavaScript measurement or with legacy browser support, this may not fit.

Alternatives and how they differ

The README names Packery and Gridster as similar systems, but they are not React-specific and require jQuery. That is a fundamental difference: react-grid-layout is React-only, so it integrates with the component lifecycle and state management. A more direct alternative is react-mosaic or react-dnd-based layouts, but the README does not mention them. Another approach is to use CSS Grid with a library like react-grid-system, which handles responsive grids but does not provide dragging or resizing. The key difference is that react-grid-layout manages both layout calculation and user interaction, whereas CSS Grid libraries only handle positioning. For a dashboard that needs drag and resize, react-grid-layout is purpose-built. For a static responsive grid, a CSS Grid solution is simpler and has no runtime measurement cost. The choice depends on whether you need interactivity or just responsive columns.

Maintenance, licensing, and upgrade cost

The repository is not archived, and the last push was July 2026, with recent releases including v2.2.4 and v2.2.3. The license is MIT, which permits commercial use and modification without a copyleft requirement, but you should verify the license text for your own legal review. The upgrade cost from v1 to v2 is significant if you adopt the full v2 API: you must rewrite layout definitions, replace WidthProvider with useContainerWidth, and adjust callback usage. The legacy wrapper reduces that cost to an import change, but you lose v2 features. The README provides a migration table and RFC links, which is helpful, but the actual effort depends on your codebase size. The changelog is referenced, so you can track changes between releases. The split API means you have two code paths to maintain, which is a long-term cost. The project appears actively maintained, but you should check the changelog for breaking changes in future minor releases.

Editorial conclusion

Adopt v2 if you are starting a new React project and want first-class TypeScript, tree-shakeable builds, and the new hooks API. Stick with the legacy wrapper if you have an existing v1 codebase and want 100% runtime compatibility without rewriting your layout code. Before adopting v2, verify your bundler supports ESM and that you can provide a measured width, since the width prop is now required and the UMD bundle is gone. If you need SSR, test the measureBeforeMount option carefully, and if you rely on onDragStart firing on mousedown, note that it now waits for 3px of movement.

Official sources

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