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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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 modeconst 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.tsindex 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 closedsetOffset(0);diff --git a/packages/core/src/Tooltip/XDSTooltip.tsx b/packages/core/src/Tooltip/XDSTooltip.tsxindex 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 modeif (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.tsnew file mode 100644index 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.tsindex 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.tsxindex 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;