Improved server rendering support for defaultSize prop (#696)

Explore the idea discussed in #692 about using `defaultSize` during the
initial render to improve server-side DevX.

> [!NOTE]
> This change is not enough to prevent layout shift _entirely_ in all
scenarios, but it should dramatically reduce it.

For example:
```tsx
<Group>
  <Panel>left</Panel>
  <Panel defaultSize="25%">right</Panel>
</Group>
```

Because of the way this library works, the eventual panel styles (after
hydration) will be:
```css
[left-panel] {
  flex: 75 1 0;
}
[right-panel] {
  flex: 25 1 0;
}
```

It's possible to server-render the right panel with a style that is
compatible with its goal style, but it's less obvious what style the
left panel should server-render with. Since neither the left panel nor
the parent group know yet about the right panel's default style, the
best the left panel can server-render with is the style this library
currently uses, meaning:
```css
[left-panel] {
  flex-grow: 1;
}
[right-panel] {
  flex-basis: 25%;
}
```

The resulting layout will be pretty close to the eventual layout, but it
won't be an exact match if the parent group uses the
[gap](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/gap)
style.

The difference can be seen with this reduced HTML example:
```html
<div style="width: 500px">
  <div>Server vs client</div>
  <div style="display: flex; gap: 1rem">
    <div style="background-color: #afa; flex-grow: 1">left</div>
    <div style="background-color: faa; flex-basis: 25%">right</div>
  </div>
  <div style="display: flex; gap: 1rem">
    <div style="background-color: #afa; flex: 75 1 0">left</div>
    <div style="background-color: #faa; flex: 25 1 0">right</div>
  </div>
</div>
```

<img width="516" height="71" alt="Screenshot 2026-03-22 at 10 03 23 AM"
src="https://github.com/user-attachments/assets/3b0cf7f7-cbdb-4877-81f1-e30597c25925"
/>

The larger the (flex) gap, the more noticeable the shift.

<img width="520" height="239" alt="Screenshot 2026-03-22 at 10 04 12 AM"
src="https://github.com/user-attachments/assets/f0046e96-3843-4359-bef1-7df3d6b77ddc"
/>

> [!NOTE]
> The layout shift shown above only applies to percentage-based sizes.
Pixels, ems/rems, and viewport based units do not exhibit this behavior.

This project's server-rendering test harness illustrates the amount of
layout shift that occurs with a moderate flex gap style. Though there's
still some layout shift, it's a big improvement over the previous
behavior.


<table><thead><tr><th>Before</th><th>After</th></tr></thead><tbody><tr><td>



https://github.com/user-attachments/assets/a4b1b07d-cd73-47ec-8d65-5db243d3a733


</td><td>


https://github.com/user-attachments/assets/add46526-e2c9-4a23-b98d-7566aab0a84e

</td></tr></tbody></table>

---

Resolves #695

Author: bvaughn

README.md

@@ -235,8 +235,8 @@ Falls back to <code>useId</code> when not provided.</p>
     <tr>
       <td>defaultSize</td>
       <td><p>Default size of Panel within its parent group; default is auto-assigned based on the total number of Panels.</p>
-<p>⚠️ This prop is useful for client side rendering but may cause problems when used with server rendering.
-It is recommended to use the <code>defaultLayout</code> prop of the parent <code>Group</code> instead.</p>
+<p>⚠️ Percentage based sizes may cause slight layout shift when server-rendering.
+For more information see the documentation.</p>
 </td>
     </tr>
     <tr>

integrations/next/app/page.tsx

@@ -10,6 +10,7 @@ export default async function Home() {
   return (
     <div className="p-2 flex flex-col gap-2">
       <LayoutShiftDetecter />
+      <div className="text-lg">Group: Default layout</div>
       <Group
         className="h-25 gap-2"
         defaultLayout={defaultLayoutOne}
@@ -59,10 +60,32 @@ export default async function Home() {
           id: bottom
         </Panel>
       </Group>
+      <div className="text-lg">Panel: Default sizes</div>
+      <DefaultSize defaultSize="25%" />
+      <DefaultSize defaultSize="100px" />
+      <DefaultSize defaultSize="25vw" />
+      <DefaultSize defaultSize="15rem" />
     </div>
   );
 }
 
+function DefaultSize({ defaultSize }: { defaultSize: string }) {
+  return (
+    <Group className="h-25 gap-2">
+      <Panel className="bg-slate-800 rounded rounded-md p-2" id="left">
+        left
+      </Panel>
+      <Panel
+        className="bg-slate-800 rounded rounded-md p-2"
+        defaultSize={defaultSize}
+        id="right"
+      >
+        right: {defaultSize}
+      </Panel>
+    </Group>
+  );
+}
+
 async function getDefaultLayout(groupId: string) {
   const api = await cookies();
   const defaultLayoutString = api.get(groupId)?.value;

integrations/vike/pages/index/+Page.tsx

@@ -23,7 +23,7 @@ export default function Page() {
   return (
     <div className="p-2 flex flex-col gap-2">
       <LayoutShiftDetecter />
-
+      <div className="text-lg">Group: Default layout</div>
       <Group className="h-25 gap-2" {...groupOneProps}>
         <Panel
           className="bg-slate-800 rounded rounded-md p-2"
@@ -68,6 +68,28 @@ export default function Page() {
           id: bottom
         </Panel>
       </Group>
+      <div className="text-lg">Panel: Default sizes</div>
+      <DefaultSize defaultSize="25%" />
+      <DefaultSize defaultSize="100px" />
+      <DefaultSize defaultSize="25vw" />
+      <DefaultSize defaultSize="15rem" />
     </div>
   );
 }
+
+function DefaultSize({ defaultSize }: { defaultSize: string }) {
+  return (
+    <Group className="h-25 gap-2">
+      <Panel className="bg-slate-800 rounded rounded-md p-2" id="left">
+        left
+      </Panel>
+      <Panel
+        className="bg-slate-800 rounded rounded-md p-2"
+        defaultSize={defaultSize}
+        id="right"
+      >
+        right: {defaultSize}
+      </Panel>
+    </Group>
+  );
+}

integrations/vite/src/routes/Home.tsx

@@ -18,7 +18,7 @@ export function HomeRoute() {
   return (
     <div className="p-2 flex flex-col gap-2">
       <LayoutShiftDetecter />
-
+      <div className="text-lg">Group: Default layout</div>
       <Group className="h-25 gap-2" {...groupOneProps}>
         <Panel
           className="bg-slate-800 rounded rounded-md p-2"
@@ -63,6 +63,28 @@ export function HomeRoute() {
           id: bottom
         </Panel>
       </Group>
+      <div className="text-lg">Panel: Default sizes</div>
+      <DefaultSize defaultSize="25%" />
+      <DefaultSize defaultSize="100px" />
+      <DefaultSize defaultSize="25vw" />
+      <DefaultSize defaultSize="15rem" />
     </div>
   );
 }
+
+function DefaultSize({ defaultSize }: { defaultSize: string }) {
+  return (
+    <Group className="h-25 gap-2">
+      <Panel className="bg-slate-800 rounded rounded-md p-2" id="left">
+        left
+      </Panel>
+      <Panel
+        className="bg-slate-800 rounded rounded-md p-2"
+        defaultSize={defaultSize}
+        id="right"
+      >
+        right: {defaultSize}
+      </Panel>
+    </Group>
+  );
+}

lib/components/group/Group.tsx

@@ -137,9 +137,11 @@ export function Group({
       }
 
       // This is unexpected except for the initial mount (before the group has registered with the global store)
-      return {
-        flexGrow: defaultLayout?.[panelId] ?? 1
-      } satisfies CSSProperties;
+      if (defaultLayout?.[panelId]) {
+        return {
+          flexGrow: defaultLayout?.[panelId]
+        } satisfies CSSProperties;
+      }
     }
   );
 

lib/components/group/types.ts

@@ -49,7 +49,10 @@ export type RegisteredGroup = Readonly<{
 
 export type GroupContextType = {
   disableCursor: boolean;
-  getPanelStyles: (groupId: string, panelId: string) => CSSProperties;
+  getPanelStyles: (
+    groupId: string,
+    panelId: string
+  ) => CSSProperties | undefined;
   id: string;
   orientation: Orientation;
   registerPanel: (panel: RegisteredPanel) => () => void;

lib/components/panel/Panel.tsx

@@ -137,15 +137,34 @@ export function Panel({
 
   usePanelImperativeHandle(id, panelRef);
 
+  // useSyncExternalStore does not support a custom equality check
+  // stringify avoids re-rendering when the style value hasn't changed
+  const read = () => {
+    const maybePanelStyles = getPanelStyles(groupId, id);
+    if (maybePanelStyles) {
+      return JSON.stringify(maybePanelStyles);
+    }
+  };
+
   const panelStylesString = useSyncExternalStore(
     (subscribe) => subscribeToMountedGroup(groupId, subscribe),
-
-    // useSyncExternalStore does not support a custom equality check
-    // stringify avoids re-rendering when the style value hasn't changed
-    () => JSON.stringify(getPanelStyles(groupId, id)),
-    () => JSON.stringify(getPanelStyles(groupId, id))
+    read,
+    read
   );
 
+  let panelStyles: CSSProperties;
+  if (panelStylesString) {
+    panelStyles = JSON.parse(panelStylesString);
+  } else if (defaultSize) {
+    panelStyles = {
+      flexGrow: undefined,
+      flexShrink: undefined,
+      flexBasis: defaultSize
+    };
+  } else {
+    panelStyles = { flexGrow: 1 };
+  }
+
   return (
     <div
       {...rest}
@@ -162,7 +181,7 @@ export function Panel({
         flexShrink: 1,
         overflow: "visible",
 
-        ...JSON.parse(panelStylesString)
+        ...panelStyles
       }}
     >
       <div

lib/components/panel/types.ts

@@ -119,8 +119,8 @@ export type PanelProps = BasePanelAttributes & {
   /**
    * Default size of Panel within its parent group; default is auto-assigned based on the total number of Panels.
    *
-   * ⚠️ This prop is useful for client side rendering but may cause problems when used with server rendering.
-   * It is recommended to use the `defaultLayout` prop of the parent `Group` instead.
+   * ⚠️ Percentage based sizes may cause slight layout shift when server-rendering.
+   * For more information see the documentation.
    */
   defaultSize?: number | string | undefined;
 

public/generated/docs/Panel.json

@@ -104,7 +104,7 @@
           "content": "<p>Default size of Panel within its parent group; default is auto-assigned based on the total number of Panels.</p>\n"
         },
         {
-          "content": "<p>This prop is useful for client side rendering but may cause problems when used with server rendering.\nIt is recommended to use the <code>defaultLayout</code> prop of the parent <code>Group</code> instead.</p>\n",
+          "content": "<p>Percentage based sizes may cause slight layout shift when server-rendering.\nFor more information see the documentation.</p>\n",
           "intent": "warning"
         }
       ],

public/generated/search-index.json

@@ -322,8 +322,8 @@
           "n": 1
         },
         "2": {
-          "v": "A Panel wraps resizable content and can be configured with min/max size constraints and collapsible behavior.\nPanel size props can be in the following formats:\n\nPercentage of the parent Group (0..100)\nPixels\nRelative font units (em, rem)\nViewport relative units (vh, vw)\n\nNumeric values are assumed to be pixels.\nStrings without explicit units are assumed to be percentages (0%..100%).\nPercentages may also be specified as strings ending with \"%\" (e.g. \"33%\")\nPixels may also be specified as strings ending with the unit \"px\".\nOther units should be specified as strings ending with their CSS property units (e.g. 1rem, 50vh)\nPanel elements always include the following attributes:\n<div data-panel data-testid=\"panel-id-prop\" id=\"panel-id-prop\">Test id can be used to narrow selection when unit testing.\nPanel elements must be direct DOM children of their parent Group elements.\n Optional propsclassName?: stringCSS class name.\nClass is applied to nested HTMLDivElement to avoid styles that interfere with Flex layout.\ncollapsedSize?: string | number = \"0%\"Panel size when collapsed; defaults to 0%.\ncollapsible?: boolean = falseThis panel can be collapsed.\nA collapsible panel will collapse when it's size is less than of the specified minSize\ndefaultSize?: string | numberDefault size of Panel within its parent group; default is auto-assigned based on the total number of Panels.\nThis prop is useful for client side rendering but may cause problems when used with server rendering.\nIt is recommended to use the defaultLayout prop of the parent Group instead.\ndisabled?: booleanWhen disabled, a panel cannot be resized either directly or indirectly (by resizing another panel).\nelementRef?: Ref<HTMLDivElement | null>Ref attached to the root HTMLDivElement.\ngroupResizeBehavior?: \"preserve-relative-size\" | \"preserve-pixel-size\" = \"preserve-relative-size\"How should this Panel behave if the parent Group is resized?\nDefaults to preserve-relative-size.\n\npreserve-relative-size: Retain the current relative size (as a percentage of the Group)\npreserve-pixel-size: Retain its current size (in pixels)\n\nPanel min/max size constraints may impact this behavior.\nA Group must contain at least one Panel with preserve-relative-size resize behavior.\nid?: string | numberUniquely identifies this panel within the parent group.\nFalls back to useId when not provided.\nThis prop is used to associate persisted group layouts with the original panel.\nThis value will also be assigned to the data-panel attribute.\nmaxSize?: string | number = \"100%\"Maximum size of Panel within its parent group; defaults to 100%.\nminSize?: string | number = \"0%\"Minimum size of Panel within its parent group; defaults to 0%.\nonResize?: ((panelSize: PanelSize, id: string | number, prevPanelSize: PanelSize | undefined) => void) | undefinedCalled when panel sizes change.\n\npanelSize Panel size (both as a percentage of the parent Group and in pixels)\nid Panel id (if one was provided as a prop)\nprevPanelSize Previous panel size (will be undefined on mount)\n\npanelRef?: Ref<PanelImperativeHandle | null>Exposes the following imperative API:\n\ncollapse(): void\nexpand(): void\ngetSize(): number\nisCollapsed(): boolean\nresize(size: number): void\n\nThe usePanelRef and usePanelCallbackRef hooks are exported for convenience use in TypeScript projects.\nstyle?: CSSPropertiesCSS properties.\nStyle is applied to nested HTMLDivElement to avoid styles that interfere with Flex layout.\n",
-          "n": 0.047
+          "v": "A Panel wraps resizable content and can be configured with min/max size constraints and collapsible behavior.\nPanel size props can be in the following formats:\n\nPercentage of the parent Group (0..100)\nPixels\nRelative font units (em, rem)\nViewport relative units (vh, vw)\n\nNumeric values are assumed to be pixels.\nStrings without explicit units are assumed to be percentages (0%..100%).\nPercentages may also be specified as strings ending with \"%\" (e.g. \"33%\")\nPixels may also be specified as strings ending with the unit \"px\".\nOther units should be specified as strings ending with their CSS property units (e.g. 1rem, 50vh)\nPanel elements always include the following attributes:\n<div data-panel data-testid=\"panel-id-prop\" id=\"panel-id-prop\">Test id can be used to narrow selection when unit testing.\nPanel elements must be direct DOM children of their parent Group elements.\n Optional propsclassName?: stringCSS class name.\nClass is applied to nested HTMLDivElement to avoid styles that interfere with Flex layout.\ncollapsedSize?: string | number = \"0%\"Panel size when collapsed; defaults to 0%.\ncollapsible?: boolean = falseThis panel can be collapsed.\nA collapsible panel will collapse when it's size is less than of the specified minSize\ndefaultSize?: string | numberDefault size of Panel within its parent group; default is auto-assigned based on the total number of Panels.\nPercentage based sizes may cause slight layout shift when server-rendering.\nFor more information see the documentation.\ndisabled?: booleanWhen disabled, a panel cannot be resized either directly or indirectly (by resizing another panel).\nelementRef?: Ref<HTMLDivElement | null>Ref attached to the root HTMLDivElement.\ngroupResizeBehavior?: \"preserve-relative-size\" | \"preserve-pixel-size\" = \"preserve-relative-size\"How should this Panel behave if the parent Group is resized?\nDefaults to preserve-relative-size.\n\npreserve-relative-size: Retain the current relative size (as a percentage of the Group)\npreserve-pixel-size: Retain its current size (in pixels)\n\nPanel min/max size constraints may impact this behavior.\nA Group must contain at least one Panel with preserve-relative-size resize behavior.\nid?: string | numberUniquely identifies this panel within the parent group.\nFalls back to useId when not provided.\nThis prop is used to associate persisted group layouts with the original panel.\nThis value will also be assigned to the data-panel attribute.\nmaxSize?: string | number = \"100%\"Maximum size of Panel within its parent group; defaults to 100%.\nminSize?: string | number = \"0%\"Minimum size of Panel within its parent group; defaults to 0%.\nonResize?: ((panelSize: PanelSize, id: string | number, prevPanelSize: PanelSize | undefined) => void) | undefinedCalled when panel sizes change.\n\npanelSize Panel size (both as a percentage of the parent Group and in pixels)\nid Panel id (if one was provided as a prop)\nprevPanelSize Previous panel size (will be undefined on mount)\n\npanelRef?: Ref<PanelImperativeHandle | null>Exposes the following imperative API:\n\ncollapse(): void\nexpand(): void\ngetSize(): number\nisCollapsed(): boolean\nresize(size: number): void\n\nThe usePanelRef and usePanelCallbackRef hooks are exported for convenience use in TypeScript projects.\nstyle?: CSSPropertiesCSS properties.\nStyle is applied to nested HTMLDivElement to avoid styles that interfere with Flex layout.\n",
+          "n": 0.048
         }
       }
     },