v4 regression: `useDefaultLayout` overwrites persisted sizes for conditionally rendered panels

[taochu]

When using conditional panels with layout persistence, the persisted layout for hidden panels gets overwritten on initial load. This worked correctly in v3 but regressed in v4.

v3 Code & Behavior (worked)

<PanelGroup
  autoSaveId="my-layout"
  direction="horizontal"
>
  <Panel order={1} id="main" defaultSize={80}>Main</Panel>
  <PanelResizeHandle />
  {showSidebar && (
    <>
      <Panel order={2} defaultSize={20} id="sidebar">Sidebar</Panel>
    </>
  )}
</PanelGroup>

v3 stored separate layouts per panel configuration:

{
  "sidebar,main": {
    "expandToSizes": {},
    "layout": [63.31, 36.69]
  },
  "main": {
    "expandToSizes": {},
    "layout": [100]
  }
}

When panels changed, v3 looked up the layout for that specific combination of panel IDs. Hidden panels didn't affect persisted layouts for other configurations.

v4 Code & Behavior (broken)

const { defaultLayout, onLayoutChange } = useDefaultLayout({
  id: 'my-layout',
  storage: localStorage,
});

<Group defaultLayout={defaultLayout} onLayoutChange={onLayoutChange}>
  <Panel id="main" defaultSize="80%">Main</Panel>
  <Separator />
  {showSidebar && (
    <>
      <Panel id="sidebar" defaultSize="20%">Sidebar</Panel>
    </>
  )}
</Group>

• Layout stored as object: { main: 80, sidebar: 20 }
• On initial render with only main visible, onLayoutChange fires with { main: 100 }
• storage.setItem overwrites stored layout → sidebar's persisted size lost
• When sidebar mounts, it falls back to defaultSize instead of the persisted value

Reproduction Steps

1. Load page with showSidebar=true
2. Resize sidebar to 30%
3. Reload page with showSidebar=false (or sidebar conditionally hidden on initial render)
4. Toggle showSidebar=true

Expected: Sidebar restores to 30%
Actual: Sidebar resets to defaultSize (20%)

Reproduction

https://codesandbox.io/p/sandbox/8hznkp

Environment

• react-resizable-panels: 4.0.16
• React: 19.2.3

[bvaughn]

I chose to change this behavior for version 4 because it simplified the integration in two ways:

1. For server environments that require saving layouts to cookies, there's a very low space limit available (4kb). Rather than saving multiple Panel layout configurations for a group, useDefaultLayout only saves the most recent one (which limits the amount of space it uses in storage).
2. It simplified the API by removing the need for useDefaultLayout to also require a panelIds array that specified which set of Panels it should try to load the layout for when calculating the initial render.
   • I considered using the most recently saved panel layout and assuming the Group would be reloaded with the same set, but that would have been an unsafe assumption in some cases (including your Code Sandbox).
   • I couldn't just return all previously saved layouts and relied on the Group to choose which one, because the group doesn't know about which panels it contains until after it has been mounted, which would have caused a visible layout change (see [Feature Request] Improve persisted client side rendering #520 and SSR Persistence Script #521 for discussion).

If you want the version 3 behavior, I think you can implement it in your own hook using the defaultLayout and onLayoutChange props:

function useDefaultLayoutV3({
  id,
  panelIds,
  storage,
}: {
  /**
   * Unique layout identifier.
   */
  id: string;

  /**
   * Set of panels currently being rendered.
   */
  panelIds: string[];

  /**
   * Storage implementation; supports localStorage, sessionStorage, and custom implementations
   * Refer to documentation site for example integrations.
   */
  storage: LayoutStorage;
}) {
  const storageKey = `react-resizable-panels:${id}:${panelIds.join(":")}`;

  // In the event that a client-only storage API is provided,
  // useSyncExternalStore prevents server/client hydration mismatch warning
  // This is not ideal; if possible a server-friendly storage API should be used
  const defaultLayoutString = useSyncExternalStore(
    subscribe,
    () => storage.getItem(storageKey),
    () => storage.getItem(storageKey)
  );

  const defaultLayout = useMemo(
    () =>
      defaultLayoutString
        ? (JSON.parse(defaultLayoutString) as Layout)
        : undefined,
    [defaultLayoutString]
  );

  const onLayoutChange = useCallback<NonNullable<OnGroupLayoutChange>>(
    (layout: Layout) => {
      try {
        storage.setItem(storageKey, JSON.stringify(layout));
      } catch (error) {
        console.error(error);
      }
    },
    [storage, storageKey]
  );

  return {
    defaultLayout,
    onLayoutChange,
  };
}

function subscribe() {
  return function unsubscribe() {};
}

Here's a fork of your Code Sandbox showing how it works:
https://codesandbox.io/p/sandbox/react-resizable-panels-repro-forked-6lsthh

[bvaughn]

I'm going to leave this issue open for a bit and think about whether it would be worth adding the panelIds prop as an optional param to useDefaultLayout.

[taochu]

Appreciate for the fast reply! 🙏

The example you gave works perfectly so I could use that in the meantime but could also see this being a common desire so some way to simplify this would be highly appreciated.

[bvaughn]

Fixed by #567; released as react-resizable-panels@4.1.0

Docs for new panelIds prop at https://react-resizable-panels.vercel.app/examples/persistent-layout/conditional-panels

---

❤️ → ☕ givebrian.coffee