Introduced autoResize prop in Panel component (#677)

This pull request introduces a new auto-resizing behavior for panels
based on issue #675, allowing individual panels to opt out of automatic
resizing when the container or window size changes.
This is achieved by adding an `autoResize` prop to the `Panel` component
and updating the core layout logic to respect this setting. Panels with
`autoResize={false}` will maintain their pixel size while other panels
absorb size changes. The update also includes new documentation, types,
test coverage, and example routes to demonstrate the feature.

**Panel auto-resize feature:**

* Added an `autoResize` prop to the `Panel` component, allowing panels
to opt out of resizing when the group/container size changes. Panels
with `autoResize={false}` keep their pixel size stable, while siblings
absorb the remaining delta.
* Updated panel types (`PanelProps`, `PanelConstraints`, etc.) and
internal state to support the new `autoResize` option.

**Layout and state management:**

* Modified the group mounting and layout validation logic to preserve
the pixel size of panels with `autoResize={false}` across group size
changes. This includes a new helper function,
`preserveNonAutoResizingPanelSizes`, and updates to state propagation
throughout the layout system.

**Documentation and examples:**

* Updated the documentation (`README.md`) to describe the new
`autoResize` prop and its usage.
* Added new example routes and navigation links to demonstrate the fixed
sidebar panel feature, including a new `AutoResizeSidebarRoute`.

**Testing:**

* Added a new test (`mountGroup.autoResize.test.ts`) to verify that
panels with `autoResize={false}` preserve their pixel size when the
group size changes.

---------

Co-authored-by: Brian Vaughn <brian.david.vaughn@gmail.com>

Author: SabbeAndres

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 4.7.0
+
+= [677](https://github.com/bvaughn/react-resizable-panels/pull/677): Add `groupResizeBehavior` prop to `Panel`, enabling panels to retain their current size (pixels) size when the parent `Group` is resized.
+
 ## 4.6.5
 
 - [670](https://github.com/bvaughn/react-resizable-panels/pull/670): Check for undefined `adoptedStyleSheets` (to better support environments like jsdom)

README.md

@@ -245,6 +245,18 @@ Falls back to <code>useId</code> when not provided.</p>
     <tr>
       <td>elementRef</td>
       <td><p>Ref attached to the root <code>HTMLDivElement</code>.</p>
+</td>
+    </tr>
+    <tr>
+      <td>groupResizeBehavior</td>
+      <td><p>How should this Panel behave if the parent Group is resized?
+Defaults to <code>preserve-relative-size</code>.</p>
+<ul>
+<li><code>preserve-relative-size</code>: Retain the current relative size (as a percentage of the Group)</li>
+<li><code>preserve-pixel-size</code>: Retain its current size (in pixels)</li>
+</ul>
+<p>ℹ️ Panel min/max size constraints may impact this behavior.</p>
+<p>⚠️ A Group must contain at least one Panel with <code>preserve-relative-size</code> resize behavior.</p>
 </td>
     </tr>
     <tr>

integrations/tests/tests/resize-events.spec.tsx

@@ -208,4 +208,106 @@ test.describe("resize events", () => {
       onLayoutChangedCount: 2
     });
   });
+
+  test('resizing the group should not impact panels with "preserve-pixel-size" behavior', async ({
+    page: mainPage
+  }) => {
+    const page = await goToUrl(
+      mainPage,
+      <Group>
+        <Panel
+          defaultSize="30%"
+          groupResizeBehavior="preserve-pixel-size"
+          id="left"
+          minSize={250}
+        />
+        <Separator />
+        <Panel id="right" minSize={50} />
+      </Group>
+    );
+
+    await expectLayout({
+      layout: {
+        left: 30,
+        right: 70
+      },
+      mainPage,
+      onLayoutChangeCount: 1,
+      onLayoutChangedCount: 1
+    });
+    await expectPanelSize({
+      mainPage,
+      onResizeCount: 1,
+      panelId: "left",
+      panelSize: {
+        asPercentage: 30,
+        inPixels: 293
+      }
+    });
+    await expectPanelSize({
+      mainPage,
+      onResizeCount: 1,
+      panelId: "right",
+      panelSize: {
+        asPercentage: 70,
+        inPixels: 683
+      }
+    });
+
+    await page.setViewportSize({
+      width: 500,
+      height: 500
+    });
+
+    await expectLayout({
+      layout: {
+        left: 62,
+        right: 38
+      },
+      mainPage,
+      onLayoutChangeCount: 2,
+      onLayoutChangedCount: 2
+    });
+    await expectPanelSize({
+      mainPage,
+      onResizeCount: 3,
+      panelId: "left",
+      panelSize: {
+        asPercentage: 62,
+        inPixels: 293
+      },
+      prevPanelSize: {
+        asPercentage: 30,
+        inPixels: 143
+      }
+    });
+    await expectPanelSize({
+      mainPage,
+      onResizeCount: 3,
+      panelId: "right",
+      panelSize: {
+        asPercentage: 38,
+        inPixels: 183
+      },
+      prevPanelSize: {
+        asPercentage: 70,
+        inPixels: 333
+      }
+    });
+
+    await page.setViewportSize({
+      width: 1000,
+      height: 500
+    });
+
+    await expectLayout({
+      layout: {
+        left: 30,
+        right: 70
+      },
+      mainPage,
+      onLayoutChangeCount: 3,
+      onLayoutChangedCount: 3
+    });
+  });
 });

lib/components/group/Group.test.tsx

@@ -1,4 +1,4 @@
-import { render } from "@testing-library/react";
+import { act, render } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import {
   createRef,
@@ -217,6 +217,128 @@ describe("Group", () => {
     });
   });
 
+  describe("groupResizeBehavior", () => {
+    function mockElementBounds({
+      groupSize,
+      leftPanelSize,
+      rightPanelSize
+    }: {
+      groupSize: number;
+      leftPanelSize: number;
+      rightPanelSize: number;
+    }) {
+      setElementBoundsFunction((element: HTMLElement) => {
+        switch (element.id) {
+          case "group": {
+            return new DOMRect(0, 0, groupSize, 50);
+          }
+          case "left": {
+            return new DOMRect(0, 0, leftPanelSize, 50);
+          }
+          case "right": {
+            return new DOMRect(leftPanelSize, 0, rightPanelSize, 50);
+          }
+        }
+      });
+    }
+
+    test("preserve-relative-size preserves relative (percentage based) size Group size changes", async () => {
+      mockElementBounds({
+        groupSize: 1,
+        leftPanelSize: 1,
+        rightPanelSize: 1
+      });
+
+      const groupRef = createRef<GroupImperativeHandle | null>();
+      const onLayoutChanged = vi.fn();
+
+      render(
+        <Group groupRef={groupRef} onLayoutChanged={onLayoutChanged}>
+          <Panel
+            defaultSize="25%"
+            groupResizeBehavior="preserve-relative-size"
+            id="left"
+          />
+          <Panel id="right" />
+        </Group>
+      );
+
+      expect(onLayoutChanged).toBeCalledTimes(1);
+      expect(onLayoutChanged).toHaveBeenLastCalledWith({
+        left: 25,
+        right: 75
+      });
+      expect(groupRef.current?.getLayout()).toEqual({
+        left: 25,
+        right: 75
+      });
+
+      await act(() => {
+        mockElementBounds({
+          groupSize: 2,
+          leftPanelSize: 1,
+          rightPanelSize: 1
+        });
+      });
+
+      expect(groupRef.current?.getLayout()).toEqual({
+        left: 25,
+        right: 75
+      });
+      expect(onLayoutChanged).toBeCalledTimes(1);
+    });
+
+    test("preserve-pixel-size preserves pixel size Group size changes", async () => {
+      mockElementBounds({
+        groupSize: 800,
+        leftPanelSize: 200,
+        rightPanelSize: 600
+      });
+
+      const groupRef = createRef<GroupImperativeHandle | null>();
+      const onLayoutChanged = vi.fn();
+
+      render(
+        <Group groupRef={groupRef} onLayoutChanged={onLayoutChanged}>
+          <Panel
+            defaultSize="25%"
+            groupResizeBehavior="preserve-pixel-size"
+            id="left"
+          />
+          <Panel id="right" />
+        </Group>
+      );
+
+      expect(onLayoutChanged).toBeCalledTimes(1);
+      expect(onLayoutChanged).toHaveBeenLastCalledWith({
+        left: 25,
+        right: 75
+      });
+      expect(groupRef.current?.getLayout()).toEqual({
+        left: 25,
+        right: 75
+      });
+
+      await act(() => {
+        mockElementBounds({
+          groupSize: 1000,
+          leftPanelSize: 200,
+          rightPanelSize: 800
+        });
+      });
+
+      expect(onLayoutChanged).toBeCalledTimes(2);
+      expect(onLayoutChanged).toHaveBeenLastCalledWith({
+        left: 20,
+        right: 80
+      });
+      expect(groupRef.current?.getLayout()).toEqual({
+        left: 20,
+        right: 80
+      });
+    });
+  });
+
   describe("defaultLayout", () => {
     test("should be ignored if it does not match Panel ids", () => {
       const onLayoutChange = vi.fn();

lib/components/panel/Panel.tsx

@@ -49,6 +49,7 @@ export function Panel({
   defaultSize,
   disabled,
   elementRef: elementRefProp,
+  groupResizeBehavior = "preserve-relative-size",
   id: idProp,
   maxSize = "100%",
   minSize = "0%",
@@ -102,6 +103,7 @@ export function Panel({
         },
         onResize: hasOnResize ? onResizeStable : undefined,
         panelConstraints: {
+          groupResizeBehavior,
           collapsedSize,
           collapsible,
           defaultSize,
@@ -114,6 +116,7 @@ export function Panel({
       return registerPanel(registeredPanel);
     }
   }, [
+    groupResizeBehavior,
     collapsedSize,
     collapsible,
     defaultSize,

lib/components/panel/types.ts

@@ -5,6 +5,10 @@ export type PanelSize = {
   inPixels: number;
 };
 
+export type GroupResizeBehavior =
+  | "preserve-relative-size"
+  | "preserve-pixel-size";
+
 /**
  * Numeric Panel constraints are represented as numeric percentages (0..100)
  * Values specified using other CSS units must be pre-converted.
@@ -14,6 +18,7 @@ export type PanelConstraints = {
   collapsible: boolean;
   defaultSize: number | undefined;
   disabled: boolean | undefined;
+  groupResizeBehavior?: GroupResizeBehavior | undefined;
   maxSize: number;
   minSize: number;
   panelId: string;
@@ -126,6 +131,22 @@ export type PanelProps = BasePanelAttributes & {
    */
   elementRef?: Ref<HTMLDivElement | null> | undefined;
 
+  /**
+   * How should this Panel behave if the parent Group is resized?
+   * Defaults to `preserve-relative-size`.
+   *
+   * - `preserve-relative-size`: Retain the current relative size (as a percentage of the Group)
+   * - `preserve-pixel-size`: Retain its current size (in pixels)
+   *
+   * ℹ️ Panel min/max size constraints may impact this behavior.
+   *
+   * ⚠️ A Group must contain at least one Panel with `preserve-relative-size` resize behavior.
+   */
+  groupResizeBehavior?:
+    | "preserve-relative-size"
+    | "preserve-pixel-size"
+    | undefined;
+
   /**
    * Uniquely identifies this panel within the parent group.
    * Falls back to `useId` when not provided.
@@ -204,6 +225,7 @@ export type PanelConstraintProps = Pick<
   | "collapsible"
   | "defaultSize"
   | "disabled"
+  | "groupResizeBehavior"
   | "maxSize"
   | "minSize"
 >;

lib/global/dom/calculatePanelConstraints.ts

@@ -11,7 +11,8 @@ export function calculatePanelConstraints(group: RegisteredGroup) {
   if (groupSize === 0) {
     // Can't calculate anything meaningful if the group has a width/height of 0
     // (This could indicate that it's within a hidden subtree)
-    return panels.map((current) => ({
+    return panels.map<PanelConstraints>((current) => ({
+      groupResizeBehavior: current.panelConstraints.groupResizeBehavior,
       collapsedSize: 0,
       collapsible: current.panelConstraints.collapsible === true,
       defaultSize: undefined,
@@ -70,6 +71,7 @@ export function calculatePanelConstraints(group: RegisteredGroup) {
     }
 
     return {
+      groupResizeBehavior: panelConstraints.groupResizeBehavior,
       collapsedSize,
       collapsible: panelConstraints.collapsible === true,
       defaultSize,