• 552: useDefaultLayout now debounces calls to storage.setItem by 150ms

• 8604491: Fix edge case bug with panel constraints not being properly invalidated after resize

• #551: Expand fixed-size element support

• #542: Clicks on higher z-index elements (e.g. modals) should not trigger separators behind them
• #547: Don't re-mount Group when defaultLayout or disableCursor props change
• #548: Bugfix: Gracefully handle Panel id changes
• #549: Improve DevX when Group within hidden DOM subtree; defer layout-change events

• #541: Don't set invalid layouts when Group is hidden or has a width/height of 0
• 40d4356: Gracefully handle invalid defaultLayout value

• f07bf00: Reset pointer-event styles after "pointerup" event

• 0796644: Account for Flex gap when calculating pointer-move delta %

• #535: Updated docs to make size and layout formats clearer

• #534: Set focus on Separator on "pointerdown"
• e08fe42: Improve iOS/Safari resize UX

• Fixed TS type for defaultLayout value returned from useDefaultLayout

• Export GroupImperativeHandle and PanelImperativeHandle types.

4.0.1

• #530: Edge case bug fix: Account for pointer resize events near edge of window/iframe

4.0.0

Version 4 of react-resizable-panels offers more flexible size constraints– supporting units as pixels, percentages, REMs/EMs, and more. Support for server-rendering (including Server Components) has also been expanded.

Migrating from version 3 to 4

Refer to the docs for a complete list of props and API methods. Below are some examples of migrating from version 3 to 4, but first a couple of potential questions:

<dl> <dt>Q: Why'd you rename <component> or <prop>?</dt> <dd>A: The most likely reason is that I think the new name more closely aligns with web standards like WAI-ARIA and CSS. For example, the <code>PanelResizeHandle</code> component was renamed to <code>Separator</code> to better align with the <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role">ARIA "separator" role</a> and the <code>direction</code> prop was renamed to <code>orientation</code> to better align with the <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation">ARIA <code>orientation</code> attribute </a>.</dd> <dt>Q: Why'd you remove support for <feature>?</dt> <dd>A: Probably because it wasn't used widely enough to justify the complexity required to maintain it. If it turns out that I'm mistaken, features can always be (re)added but it's more difficult to remove them.</dd> <dt>Q: Were the <code>onCollapse</code> and <code>onExpand</code> event handlers removed?</dt> <dd>A: Yes. Use the <code>onResize</code> event handler instead:

onResize={(size) => {
  // Either this
  const isCollapsed = size === collapsedSize;

  // Or this:
  panelRef.isCollapsed();
}}

</dd> </dl>

Basic usage example

// Version 3

import { PanelGroup, Panel, PanelResizeHandle } from "react-resizable-panels";

<PanelGroup direction="horizontal">
  <Panel defaultSize={30} minSize={20}>left</Panel>
  <PanelResizeHandle />
  <Panel defaultSize={30} minSize={20}>right</Panel>
</PanelGroup>

// Version 4

import { Group, Panel, Separator } from "react-resizable-panels";

<Group orientation="horizontal">
  <Panel defaultSize={30} minSize={20}>left</Panel>
  <Separator />
  <Panel defaultSize={30} minSize={20}>right</Panel>
</Group>

Persistent layouts using localStorage

// Version 3

import { PanelGroup, Panel, PanelResizeHandle } from "react-resizable-panels";

<PanelGroup autoSaveId="unique-group-id" direction="horizontal">
  <Panel>left</Panel>
  <PanelResizeHandle />
  <Panel>right</Panel>
</PanelGroup>

// Version 4

import { Group, Panel, Separator, useDefaultLayout } from "react-resizable-panels";

const { defaultLayout, onLayoutChange } = useDefaultLayout({
  groupId: "unique-group-id",
  storage: localStorage
});

<Group defaultLayout={defaultLayout} onLayoutChange={onLayoutChange}>
  <Panel>left</Panel>
  <Separator />
  <Panel>right</Panel>
</Group>

[!NOTE] Refer to the docs for examples of persistent layouts with server rendering and server components.

Conditional panels

// Version 3

import { PanelGroup, Panel, PanelResizeHandle } from "react-resizable-panels";

<PanelGroup autoSaveId="unique-group-id" direction="horizontal">
   {showLeftPanel && (
     <>
       <Panel id="left" order={1}>left</Panel>
       <PanelResizeHandle />
     </>
   )}
   <Panel id="center" order={2}>center</Panel>
   {showRightPanel && (
     <>
       <PanelResizeHandle />
       <Panel id="right" order={3}>right</Panel>
     </>
   )}
</PanelGroup>

// Version 4

import { Group, Panel, Separator } from "react-resizable-panels";

<Group>
  {showLeftPanel && (
    <>
      <Panel id="left">left</Panel>
      <Separator />
    </>
  )}
  <Panel id="center">center</Panel>
  {showRightPanel && (
    <>
      <Separator />
      <Panel id="right">right</Panel>
    </>
  )}
</Group>

Imperative APIs

// Version 3

import { PanelGroup, Panel, PanelResizeHandle } from "react-resizable-panels";
import type { ImperativePanelGroupHandle, ImperativePanelHandle }from "react-resizable-panels";

 const panelRef = useRef<ImperativePanelHandle>(null);
 const panelGroupRef = useRef<ImperativePanelGroupHandle>(null);

<PanelGroup direction="horizontal" ref={panelGroupRef}>
  <Panel ref={panelRef}>left</Panel>
  <PanelResizeHandle />
  <Panel>right</Panel>
</PanelGroup>

// Version 4

import { Group, Panel, Separator, useGroupRef, usePanelRef } from "react-resizable-panels";

const groupRef = useGroupRef();
const panelRef = usePanelRef();

<Group groupRef={groupRef} orientation="horizontal">
  <Panel panelRef={panelRef}>left</Panel>
  <Separator />
  <Panel>right</Panel>
</Group>

• #517: Fixed Firefox bug that caused resizing to be interrupted unexpected

• #512: Fixed size precision regression from 2.0.17

• #503: Support custom cursors

• #492: Fix compatibility with Cloudflare workers

• Fallback for type of HTMLElement to better support portal edge cases

• #479: Improve support for Cloudflare Workers and Vercel Functions
• #480: Fixed package.json#types reference

• #478: Module is ESM-only in order to better work with modern tooling.
• #475: "pointerup" and "pointercancel" listeners are now attached to the ownerDocument body to better support edge cases like portals being rendered into a child window.

• #427: Stacking order checks also check for SVGElements (bug fix)
• #433: Exclude src directory from NPM package

• Removed "engines" block and replaced with "packageManager"
• Don't read document.direction for RTL detection; use inherited style instead

• Add react v19 to peer deps

• Improve TypeScript HTML tag type generics (#407)
• Edge case check to make sure resize handle hasn't been unmounted while dragging (#410)

• Edge case bug fix for a resize handle unmounting while being dragged (#402)

• Suppress invalid layout warning for empty panel groups (#396)

• Fix onDragging regression (#391)
• Fix cursor icon behavior in nested panels (#390)

• Add opt-in support for setting the "nonce" attribute for the global cursor style (#386)
• Support disabling global cursor styles (#387)

• Improve obfuscation for React.useId references (#382)

• Force eager layout re-calculation after panel added/removed (#375)

• Handle pointer event edge case with different origin iframes (#374)

• Reset global cursor if an active resize handle is unmounted (#313)
• Resize handle supports (optional) onFocus or onBlur props (#370)

• Add optional minSize override param to panel expand imperative API

• Inline object hitAreaMargins will not trigger re-initialization logic unless inner values change (#342)

• Prevent pointer events handled by resize handles from triggering elements behind/underneath (#338)

• Replaced .toPrecision() with .toFixed() to avoid undesirable layout shift (#323)

• Better account for high-precision sizes with onCollapse and onExpand callbacks (#325)

• Better account for high-precision collapsedSize values (#325)

• Fix potential cycle in stacking-order logic for an unmounted node (#317)

• Improve resize for edge cases with collapsed panels; intermediate resize states should now fall back to the most recent valid layout rather than the initial layout (#311)

• Fix resize handle cursor hit detection when when viewport is scrolled (#305)

• Fix conditional layout edge case (#309)

• Fix Flex stacking context bug (#301)
• Fix case where pointer event listeners were sometimes added to the document unnecessarily

• Panel/PanelGroup/`PanelResizeHandle`` pass "id" prop through to DOM (#299)
• Panel attributes data-panel-collapsible and data-panel-size are no longer DEV-only (#297)