Registry / web-framework / react-resizable-panels

react-resizable-panels

library4.10.0jsnpmunverified

react-resizable-panels provides a robust and accessible solution for building resizable panel groups and layouts in React applications. Currently at version 4.10.0, the library maintains an active development pace with frequent patch and minor releases, reflecting ongoing enhancements and bug fixes. Key differentiators include flexible size constraints supporting various units (pixels, percentages, REMs/EMs, viewport units), improved server-side rendering support for both traditional SSR and React Server Components, and a declarative API complemented by imperative escape hatches via refs. It focuses on smooth user interactions with drag, double-click to reset, and keyboard accessibility for resizing, making it suitable for complex UIs like IDEs or dashboards. The library also supports persistent layouts via `useDefaultLayout` and offers granular control over resize behavior, building on a foundation of performance and robustness by its author.

web-framework

npm install react-resizable-panels

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-RESIZABLE-PA

react-resizable-panels

web-frameworkjavascriptv4.10.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Group

✓ import { Group } from 'react-resizable-panels';

✗ import { PanelGroup } from 'react-resizable-panels';

The `PanelGroup` component was renamed to `Group` in v4 to align with ARIA standards.

Panel

✓ import { Panel } from 'react-resizable-panels';

Used to define individual resizable sections within a `Group`.

Separator

✓ import { Separator } from 'react-resizable-panels';

✗ import { PanelResizeHandle } from 'react-resizable-panels';

The `PanelResizeHandle` component was renamed to `Separator` in v4 for better ARIA alignment.

useDefaultLayout

✓ import { useDefaultLayout } from 'react-resizable-panels';

Hook for managing and persisting layout state, including automatic migration of legacy layout formats since v4.8.0. It's recommended to debounce calls to storage.setItem.

This quickstart demonstrates a nested resizable layout using `Group`, `Panel`, and `Separator` components, showcasing horizontal and vertical orientations and how to handle layout changes.

import React from 'react'; import { Group, Panel, Separator } from 'react-resizable-panels'; function MyResizableLayout() { const onLayoutChange = (sizes: number[]) => { // This callback fires frequently during drag. For saving, prefer onLayoutChanged. console.log('Layout changing:', sizes); }; const onLayoutChanged = (sizes: number[]) => { // This callback fires once after dragging is complete. console.log('Layout changed and settled:', sizes); // You might save `sizes` to localStorage here, e.g., // localStorage.setItem('my-app-layout', JSON.stringify(sizes)); }; return ( <div style={{ height: '500px', display: 'flex', border: '1px solid #ccc' }}> <Group direction="horizontal" onLayoutChange={onLayoutChange} onLayoutChanged={onLayoutChanged}> <Panel defaultSize={20} minSize={10}> <div style={{ padding: '10px', background: '#f0f0f0', height: '100%' }}> Sidebar </div> </Panel> <Separator style={{ background: '#ddd', width: '8px', cursor: 'ew-resize' }} /> <Panel defaultSize={60} minSize={30}> <Group direction="vertical"> <Panel defaultSize={70} minSize={20}> <div style={{ padding: '10px', background: '#e0e0e0', height: '100%' }}> Main Content (Top) </div> </Panel> <Separator style={{ background: '#ccc', height: '8px', cursor: 'ns-resize' }} /> <Panel defaultSize={30} minSize={15}> <div style={{ padding: '10px', background: '#d0d0d0', height: '100%' }}> Main Content (Bottom) </div> </Panel> </Group> </Panel> <Separator style={{ background: '#bbb', width: '8px', cursor: 'ew-resize' }} /> <Panel defaultSize={20} minSize={10}> <div style={{ padding: '10px', background: '#c0c0c0', height: '100%' }}> Right Panel </div> </Panel> </Group> </div> ); } export default MyResizableLayout;

Debug

Known issues

breakingThe `PanelGroup` component was renamed to `Group`, and `PanelResizeHandle` to `Separator` in v4. Applications upgrading from v3 must update import statements and component usage. Additionally, the `direction` prop was renamed to `orientation` on `Group` components.

fix

Update imports from `PanelGroup` to `Group` and `PanelResizeHandle` to `Separator`. Change `direction="horizontal"` or `direction="vertical"` to `orientation="horizontal"` or `orientation="vertical"` respectively.

affects: >=4.0.0

breakingThe `Panel` component's `aria-disabled` attribute was replaced with `data-disabled` in v4.7.6. Any custom CSS or accessibility queries targeting `[aria-disabled='true']` on `Panel` elements will no longer function as expected.

fix

Update CSS selectors and accessibility checks to target `[data-disabled='true']` instead of `[aria-disabled='true']` for `Panel` components.

affects: >=4.7.6

gotchaWhen using the `style` prop on a `Group` component, certain CSS properties (`display`, `flex-direction`, `flex-wrap`, and `overflow`) cannot be overridden by user-provided styles.

fix

Avoid attempting to override these specific CSS properties directly on the `Group` component's `style` prop. Adjust parent container styles or wrap `Group` in another `div` for layout adjustments if necessary.

affects: >=4.0.0

gotchaThe `onLayoutChange` callback fires frequently during pointer events (e.g., while dragging a separator), which can lead to performance issues or excessive state updates if used for saving layouts.

fix

For persistent layout saving or actions that should occur once per resize operation, use the `onLayoutChanged` callback instead, which fires only after the pointer has been released.

affects: >=4.0.0

gotchaServer-side rendering (SSR) of panels with percentage-based `defaultSize` props may cause a slight layout shift on initial render.

fix

Refer to the official documentation for strategies to minimize SSR layout shift, which often involves pre-calculating pixel sizes or using a loading state.

affects: >=4.0.0

gotchaThe `useDefaultLayout` hook automatically migrates legacy layout formats to the v4 structure, but developers should be aware of this behavior, especially if manually managing layout persistence.

fix

While `useDefaultLayout` handles migration, review the migration guide from v3 to v4 for API changes (e.g., `onCollapse`/`onExpand` removed, `direction` to `orientation`, `PanelResizeHandle` to `Separator`) if manually managing or debugging layout persistence.

affects: >=4.8.0

gotchaThe `useDefaultLayout` hook in versions prior to 4.0.12 did not debounce calls to `storage.setItem`. This could lead to excessive storage writes during rapid resizing.

fix

Upgrade to `react-resizable-panels@4.0.12` or higher, where `useDefaultLayout` now defaults to debouncing `storage.setItem` calls by 150ms. If you require immediate saving for specific scenarios (e.g., unit tests), you can explicitly set `debounceSaveMs: 0` in the `useDefaultLayout` options.

affects: <4.0.12

Errors

Common errors & fixes

TS2339: Property 'PanelGroup' does not exist on type 'typeof import("react-resizable-panels")'.

Attempting to import or use `PanelGroup` which was renamed to `Group` in v4.

fix

Change `import { PanelGroup } from 'react-resizable-panels';` to `import { Group } from 'react-resizable-panels';`

TS2339: Property 'PanelResizeHandle' does not exist on type 'typeof import("react-resizable-panels")'.

Attempting to import or use `PanelResizeHandle` which was renamed to `Separator` in v4.

fix

Change `import { PanelResizeHandle } from 'react-resizable-panels';` to `import { Separator } from 'react-resizable-panels';`

Error: React.Children.only expected to receive a single React element child.

A `Group` or `Panel` component received multiple children where only one was expected, or an incorrect nesting structure was used.

fix

Ensure that `Group` components directly contain `Panel` and `Separator` components, and that `Panel` components contain a single React element as their child content.

Layout does not persist or save correctly after resizing.

Incorrect usage of `onLayoutChange` instead of `onLayoutChanged` for saving state, or issues with the `defaultLayout` prop or `useDefaultLayout` hook.

fix

Use the `onLayoutChanged` prop on the `Group` component for saving the layout, as it fires reliably after a resize operation is complete. For automatic persistence, ensure `useDefaultLayout` is configured correctly with an `id` and `storage` mechanism.

Upgrade

Version history

4.10.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React applications.

react-domrequiredPeer dependency for rendering React components to the DOM.

Agent activity

6 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bvaughn/react-resizable-panels ↗

packagehttps://www.npmjs.com/package/react-resizable-panels ↗

homepagehttps://react-resizable-panels.vercel.app/ ↗