Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(ssr): replace useLayoutEffect with SSR-safe alternatives (#1721)

Cindy Zhang894eeaee4c18
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 4271d6b65f..ae9b0133e3 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -482,8 +482,8 @@ export function XDSAppShell({
// =========================================================================
// Slot presence — checks whether slot containers have rendered DOM content.
- // Refs are attached to wrapper divs around each slot; useLayoutEffect checks
- // childNodes so presence is known before paint.
+ // Refs are attached to wrapper divs around each slot; a MutationObserver
+ // checks childNodes to track whether each slot has rendered content.
// =========================================================================
const {ref: topNavRef, hasContent: hasTopNavContent} = useXDSSlotPresence(
topNav != null,
diff --git a/packages/core/src/AppShell/useXDSSlotPresence.tsx b/packages/core/src/AppShell/useXDSSlotPresence.tsx
index 417eb31778..de40772f2a 100644
--- a/packages/core/src/AppShell/useXDSSlotPresence.tsx
+++ b/packages/core/src/AppShell/useXDSSlotPresence.tsx
@@ -2,7 +2,7 @@
/**
* @file useXDSSlotPresence.tsx
- * @input Uses React useCallback, useLayoutEffect, useRef, useState
+ * @input Uses React useCallback, useEffect, useRef, useState
* @output Exports useXDSSlotPresence hook
* @position Internal hook for detecting whether slot containers have rendered content.
*
@@ -16,7 +16,7 @@
* ref) — only one mounts at a time, and the hook observes whichever is active.
*/
-import {useCallback, useLayoutEffect, useRef, useState} from 'react';
+import {useCallback, useEffect, useRef, useState} from 'react';
function hasChildContent(el: HTMLElement): boolean {
for (let i = 0; i < el.childNodes.length; i++) {
@@ -82,7 +82,7 @@ export function useXDSSlotPresence(initialValue = false) {
}, []);
// Clean up on unmount
- useLayoutEffect(() => {
+ useEffect(() => {
return () => {
if (observerRef.current) {
observerRef.current.disconnect();
diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.tsx b/packages/core/src/CodeBlock/XDSCodeBlock.tsx
index cc0a73b2e4..7509029194 100644
--- a/packages/core/src/CodeBlock/XDSCodeBlock.tsx
+++ b/packages/core/src/CodeBlock/XDSCodeBlock.tsx
@@ -7,7 +7,7 @@
*/
import {
- useLayoutEffect,
+ useInsertionEffect,
useEffect,
useRef,
useState,
@@ -436,7 +436,7 @@ function SpanCodeContent({
isWrapped: boolean;
sizeStyle: stylex.StyleXStyles;
}) {
- useLayoutEffect(() => {
+ useInsertionEffect(() => {
ensureHighlightStyles();
}, []);
diff --git a/packages/core/src/HoverCard/XDSHoverCard.tsx b/packages/core/src/HoverCard/XDSHoverCard.tsx
index 8c4fb96c38..271434b554 100644
--- a/packages/core/src/HoverCard/XDSHoverCard.tsx
+++ b/packages/core/src/HoverCard/XDSHoverCard.tsx
@@ -14,11 +14,11 @@
import React, {
useCallback,
- useLayoutEffect,
useRef,
type ReactElement,
type ReactNode,
} from 'react';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import * as stylex from '@stylexjs/stylex';
import {useXDSHoverCard, type HoverCardFocusTrigger} from './useXDSHoverCard';
import type {LayerAlignment, LayerPlacement} from '../Layer/useXDSLayer';
@@ -189,7 +189,7 @@ export function XDSHoverCard({
});
// For element children with display:contents, attach ref to first child
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
if (textOnly) return; // Skip for text-only (ref is on wrapper)
const wrapper = wrapperRef.current;
diff --git a/packages/core/src/Kbd/XDSKbd.tsx b/packages/core/src/Kbd/XDSKbd.tsx
index 9a2de05ede..6b4591cf8d 100644
--- a/packages/core/src/Kbd/XDSKbd.tsx
+++ b/packages/core/src/Kbd/XDSKbd.tsx
@@ -11,7 +11,8 @@
* - /packages/core/src/Kbd/index.ts
*/
-import {useState, useLayoutEffect} from 'react';
+import {useState} from 'react';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import * as stylex from '@stylexjs/stylex';
import {xdsClassName, mergeProps} from '../utils';
import type {XDSBaseProps} from '../XDSBaseProps';
@@ -122,7 +123,7 @@ export interface XDSKbdProps extends XDSBaseProps<HTMLSpanElement> {
*
* Platform-aware: `mod` renders as ⌘ on macOS and Ctrl elsewhere.
* SSR-safe — defers platform detection to a layout effect to avoid
- * hydration mismatches. Uses useLayoutEffect so the platform-correct
+ * hydration mismatches. Uses useIsomorphicLayoutEffect so the platform-correct
* symbol is set before the browser paints (no visible flicker).
*
* @example
@@ -133,7 +134,7 @@ export interface XDSKbdProps extends XDSBaseProps<HTMLSpanElement> {
export function XDSKbd({keys, xstyle, className, style, ...rest}: XDSKbdProps) {
const [isMac, setIsMac] = useState(false);
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
setIsMac(detectMac());
}, []);
diff --git a/packages/core/src/Popover/XDSPopover.tsx b/packages/core/src/Popover/XDSPopover.tsx
index baa9dc0cee..bce56b5fca 100644
--- a/packages/core/src/Popover/XDSPopover.tsx
+++ b/packages/core/src/Popover/XDSPopover.tsx
@@ -16,11 +16,11 @@
import React, {
useCallback,
- useLayoutEffect,
useRef,
type ReactElement,
type ReactNode,
} from 'react';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import * as stylex from '@stylexjs/stylex';
import {xdsClassName, mergeProps} from '../utils';
import type {StyleXStyles} from '@stylexjs/stylex';
@@ -342,7 +342,7 @@ export function XDSPopover({
);
// Sibling mode: attach to external anchorRef
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
if (!anchorRef) return;
const el = anchorRef.current;
@@ -371,7 +371,7 @@ export function XDSPopover({
// Children mode: use wrapper as CSS anchor, find button inside for
// ARIA + event handlers.
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
if (anchorRef) return; // Skip if using anchorRef mode
const wrapper = wrapperRef.current;
@@ -400,7 +400,7 @@ export function XDSPopover({
}, [anchorRef, popover, attachTrigger]);
// Sync controlled state
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
if (!isControlled) return;
if (isOpen && !popover.isOpen) {
popover.show();
diff --git a/packages/core/src/Selector/hooks.ts b/packages/core/src/Selector/hooks.ts
index daff27a5e4..6d5712b579 100644
--- a/packages/core/src/Selector/hooks.ts
+++ b/packages/core/src/Selector/hooks.ts
@@ -6,7 +6,8 @@
* @position Internal hooks; used by XDSSelector.tsx
*/
-import {useCallback, useLayoutEffect, useRef, useState} from 'react';
+import {useCallback, useRef, useState} from 'react';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import type {RefObject} from 'react';
import type {XDSSelectorOptionData} from './types';
@@ -47,7 +48,7 @@ export function useSelectedItemOffset({
const [offset, setOffset] = useState(0);
const [isPositioned, setIsPositioned] = useState(false);
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
if (!isOpen) {
// Reset offset when closed
setOffset(0);
diff --git a/packages/core/src/Tooltip/XDSTooltip.tsx b/packages/core/src/Tooltip/XDSTooltip.tsx
index 01a1ce4861..d5fccf659b 100644
--- a/packages/core/src/Tooltip/XDSTooltip.tsx
+++ b/packages/core/src/Tooltip/XDSTooltip.tsx
@@ -13,11 +13,11 @@
import React, {
useCallback,
- useLayoutEffect,
useRef,
type ReactElement,
type ReactNode,
} from 'react';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import * as stylex from '@stylexjs/stylex';
import {useXDSTooltip, type TooltipFocusTrigger} from './useXDSTooltip';
import type {LayerAlignment, LayerPlacement} from '../Layer/useXDSLayer';
@@ -199,7 +199,7 @@ export function XDSTooltip({
});
// Sibling mode: attach to external anchorRef
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
if (!anchorRef) return;
const el = anchorRef.current;
@@ -226,7 +226,7 @@ export function XDSTooltip({
}, [anchorRef, tooltip.ref, tooltip.describedBy]);
// For element children with display:contents, attach ref to first child
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
if (anchorRef) return; // Skip if using anchorRef mode
if (textOnly) return; // Skip for text-only (ref is on wrapper)
diff --git a/packages/core/src/hooks/useIsomorphicLayoutEffect.ts b/packages/core/src/hooks/useIsomorphicLayoutEffect.ts
new file mode 100644
index 0000000000..93614ccb48
--- /dev/null
+++ b/packages/core/src/hooks/useIsomorphicLayoutEffect.ts
@@ -0,0 +1,18 @@
+/**
+ * @file useIsomorphicLayoutEffect.ts
+ * @input React useLayoutEffect, useEffect
+ * @output Exports useIsomorphicLayoutEffect
+ * @position Internal utility; used by components that need useLayoutEffect
+ * but must avoid the SSR warning React emits when useLayoutEffect runs
+ * on the server (where there is no DOM to synchronously measure).
+ *
+ * On the client this is useLayoutEffect; on the server it falls back to
+ * useEffect (which is a no-op during SSR anyway). The runtime behavior is
+ * identical — neither hook fires during server rendering — but React only
+ * warns about useLayoutEffect.
+ */
+
+import {useEffect, useLayoutEffect} from 'react';
+
+export const useIsomorphicLayoutEffect =
+ typeof window !== 'undefined' ? useLayoutEffect : useEffect;
diff --git a/packages/core/src/hooks/useOverflow.ts b/packages/core/src/hooks/useOverflow.ts
index 7f8fa8f50c..dc9e9aa4e9 100644
--- a/packages/core/src/hooks/useOverflow.ts
+++ b/packages/core/src/hooks/useOverflow.ts
@@ -2,7 +2,7 @@
/**
* @file useOverflow.ts
- * @input Uses React useState, useLayoutEffect, useCallback, useRef
+ * @input Uses React useState, useCallback, useRef; useIsomorphicLayoutEffect
* @output Exports useOverflow hook for measuring and managing horizontal overflow
* @position Core hook; used by XDSOverflowList and consumers for overflow patterns
*
@@ -14,8 +14,8 @@
* - /packages/core/src/hooks/index.ts
*/
-
-import {useState, useLayoutEffect, useCallback, useRef} from 'react';
+import {useState, useCallback, useRef} from 'react';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
export interface UseOverflowOptions {
/**
@@ -200,7 +200,7 @@ export function useOverflow(
);
// Recalculate when itemCount changes
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
calculate();
}, [calculate]);
diff --git a/packages/core/src/theme/XDSTheme.tsx b/packages/core/src/theme/XDSTheme.tsx
index 4b90a069fe..ea3a94fe94 100644
--- a/packages/core/src/theme/XDSTheme.tsx
+++ b/packages/core/src/theme/XDSTheme.tsx
@@ -32,13 +32,8 @@
* ```
*/
-import React, {
- useId,
- useInsertionEffect,
- useLayoutEffect,
- useMemo,
- useRef,
-} from 'react';
+import React, {useId, useInsertionEffect, useMemo, useRef} from 'react';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import * as stylex from '@stylexjs/stylex';
import type {ThemeMode} from './types';
import {colorVars, typographyVars} from './tokens.stylex';
@@ -174,7 +169,7 @@ function useThemeStyleInjection(theme: XDSDefinedTheme): void {
/**
* Hook that loads fonts declared in theme.fonts at runtime.
*
- * Uses useLayoutEffect to inject font stylesheets before the browser paints,
+ * Uses useIsomorphicLayoutEffect to inject font stylesheets before the browser paints,
* minimizing flash of unstyled text (FOUT).
*
* This is the fallback loading path — the preferred approach is to add
@@ -187,7 +182,7 @@ function useThemeStyleInjection(theme: XDSDefinedTheme): void {
function useThemeFontLoading(theme: XDSDefinedTheme): void {
const injectedLinksRef = useRef<HTMLLinkElement[]>([]);
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
if (typeof document === 'undefined') return;
if (!theme.fonts || theme.fonts.length === 0) return;
@@ -263,7 +258,7 @@ function useRootThemeSync(
mode: ThemeMode,
themeName: string,
): void {
- useLayoutEffect(() => {
+ useIsomorphicLayoutEffect(() => {
if (isNested) return;
if (typeof document === 'undefined') return;