Skip to content

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

TypeScript

feat(core): add module-level registerIcons() for RSC compatibility (#528)

Cindy Zhang44a8529e1d54
diff --git a/packages/core/src/Icon/IconRegistry.tsx b/packages/core/src/Icon/IconRegistry.tsx
index f19f14891e..d505588fc0 100644
--- a/packages/core/src/Icon/IconRegistry.tsx
+++ b/packages/core/src/Icon/IconRegistry.tsx
@@ -1,55 +1,27 @@
/**
* @file IconRegistry.tsx
- * @input Uses React createContext, useContext, ReactNode
- * @output Exports IconRegistryContext, useXDSIcon hook, XDSIconName, XDSIconRegistry types
- * @position Core icon infrastructure; consumed by components that need internal icons
+ * @input Uses React createContext, useContext
+ * @output Exports IconRegistryContext, useXDSIcon hook
+ * @position Client-side icon context; wraps the global registry with
+ * React Context support for tree-scoped overrides via XDSTheme.
+ *
+ * For server components, use getIcon() from globalIconRegistry.tsx instead.
*
* SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Icon/globalIconRegistry.tsx (global registry, types)
* - /packages/core/src/Icon/Icon.doc.mjs (features, usage)
* - /packages/core/src/Icon/index.ts (exports)
- * - /packages/core/src/Icon/defaultIcons.tsx (fallback icon set)
*/
'use client';
import {createContext, useContext, type ReactNode} from 'react';
import {defaultIcons} from './defaultIcons';
+import type {XDSIconName, XDSIconRegistry} from './globalIconRegistry';
+import {getGlobalRegistry} from './globalIconRegistry';
-// =============================================================================
-// Types
-// =============================================================================
-
-/**
- * Semantic icon names used internally by XDS components.
- *
- * These represent the functional purpose of each icon, not a specific
- * visual representation. Themes provide the actual icon components.
- */
-export type XDSIconName =
- | 'close'
- | 'chevronDown'
- | 'chevronLeft'
- | 'chevronRight'
- | 'check'
- | 'checkCircle'
- | 'xCircle'
- | 'warning'
- | 'info'
- | 'calendar'
- | 'clock'
- | 'externalLink'
- | 'menu'
- | 'moreHorizontal'
- | 'search';
-
-/**
- * Icon registry mapping semantic names to React nodes.
- *
- * Themes provide this to override the built-in fallback icons.
- * Values can be any ReactNode: SVG components, font icon spans,
- * unicode characters, or any other renderable content.
- */
-export type XDSIconRegistry = Record<XDSIconName, ReactNode>;
+// Re-export types so existing imports from this file still work
+export type {XDSIconName, XDSIconRegistry} from './globalIconRegistry';
// =============================================================================
// Context
@@ -58,7 +30,7 @@ export type XDSIconRegistry = Record<XDSIconName, ReactNode>;
/**
* Context for providing theme icons to components.
* Accepts a full or partial registry. When null, components fall back
- * to built-in lightweight SVGs. Partial registries fall back per-icon.
+ * to the global registry, then to built-in lightweight SVGs.
*/
export const IconRegistryContext =
createContext<Partial<XDSIconRegistry> | null>(null);
@@ -68,24 +40,34 @@ export const IconRegistryContext =
// =============================================================================
/**
- * Hook to retrieve an icon by semantic name.
+ * Hook to retrieve an icon by semantic name (client components only).
*
* Resolution order:
- * 1. Theme icon registry (via IconRegistryContext) — if the name exists
- * 2. Built-in lightweight SVG fallback
+ * 1. Context registry (via XDSTheme's IconRegistryContext)
+ * 2. Global registry (via registerIcons())
+ * 3. Built-in lightweight SVG fallback
+ *
+ * For server components, use getIcon() from iconRegistry.ts instead.
*
* @example
* ```
* const closeIcon = useXDSIcon('close');
- * // Returns the theme's close icon, or the built-in SVG fallback
* ```
*/
export function useXDSIcon(name: XDSIconName): ReactNode {
- const registry = useContext(IconRegistryContext);
+ const contextRegistry = useContext(IconRegistryContext);
+ const globalRegistry = getGlobalRegistry();
+
+ // Context wins (tree-scoped theme override)
+ if (contextRegistry != null && contextRegistry[name] != null) {
+ return contextRegistry[name];
+ }
- if (registry != null && registry[name] != null) {
- return registry[name];
+ // Global registry (module-level, works server-side too)
+ if (globalRegistry[name] != null) {
+ return globalRegistry[name];
}
+ // Built-in fallback
return defaultIcons[name];
}
diff --git a/packages/core/src/Icon/globalIconRegistry.test.tsx b/packages/core/src/Icon/globalIconRegistry.test.tsx
new file mode 100644
index 0000000000..bf79871a41
--- /dev/null
+++ b/packages/core/src/Icon/globalIconRegistry.test.tsx
@@ -0,0 +1,49 @@
+import {describe, it, expect, beforeEach} from 'vitest';
+import {registerIcons, getIcon, resetIcons} from './globalIconRegistry';
+
+describe('iconRegistry (global, RSC-compatible)', () => {
+ beforeEach(() => {
+ resetIcons();
+ });
+
+ it('returns default icons when nothing is registered', () => {
+ const icon = getIcon('close');
+ expect(icon).toBeDefined();
+ expect(icon).not.toBeNull();
+ });
+
+ it('returns registered icons over defaults', () => {
+ const customClose = 'custom-close-icon';
+ registerIcons({close: customClose});
+ expect(getIcon('close')).toBe(customClose);
+ });
+
+ it('falls back to defaults for unregistered names', () => {
+ registerIcons({close: 'custom-close'});
+ // 'check' was not registered, should fall back to default
+ const checkIcon = getIcon('check');
+ expect(checkIcon).toBeDefined();
+ expect(checkIcon).not.toBe('custom-close');
+ });
+
+ it('merges multiple registerIcons calls', () => {
+ registerIcons({close: 'close-v1'});
+ registerIcons({check: 'check-v1'});
+ expect(getIcon('close')).toBe('close-v1');
+ expect(getIcon('check')).toBe('check-v1');
+ });
+
+ it('later registrations override earlier ones', () => {
+ registerIcons({close: 'close-v1'});
+ registerIcons({close: 'close-v2'});
+ expect(getIcon('close')).toBe('close-v2');
+ });
+
+ it('resetIcons clears the global registry', () => {
+ registerIcons({close: 'custom'});
+ expect(getIcon('close')).toBe('custom');
+ resetIcons();
+ // Should fall back to default
+ expect(getIcon('close')).not.toBe('custom');
+ });
+});
diff --git a/packages/core/src/Icon/globalIconRegistry.tsx b/packages/core/src/Icon/globalIconRegistry.tsx
new file mode 100644
index 0000000000..1797db1a36
--- /dev/null
+++ b/packages/core/src/Icon/globalIconRegistry.tsx
@@ -0,0 +1,99 @@
+/**
+ * @file globalIconRegistry.tsx
+ * @input None (pure module-level state)
+ * @output Exports registerIcons, getIcon, resetIcons, XDSIconName, XDSIconRegistry
+ * @position Global icon registry; works in both server and client environments
+ *
+ * This module has NO 'use client' directive — it's importable from RSC.
+ * Components that need icons in server components use getIcon() directly.
+ * Client components use useXDSIcon() from IconRegistryContext.tsx which
+ * checks context first, then falls back to this global registry.
+ */
+
+import type {ReactNode} from 'react';
+import {defaultIcons} from './defaultIcons';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Semantic icon names used internally by XDS components.
+ *
+ * These represent the functional purpose of each icon, not a specific
+ * visual representation. Themes provide the actual icon components.
+ */
+export type XDSIconName =
+ | 'close'
+ | 'chevronDown'
+ | 'chevronLeft'
+ | 'chevronRight'
+ | 'check'
+ | 'checkCircle'
+ | 'xCircle'
+ | 'warning'
+ | 'info'
+ | 'calendar'
+ | 'clock'
+ | 'externalLink'
+ | 'menu'
+ | 'moreHorizontal'
+ | 'search';
+
+/**
+ * Icon registry mapping semantic names to React nodes.
+ */
+export type XDSIconRegistry = Record<XDSIconName, ReactNode>;
+
+// =============================================================================
+// Global Registry
+// =============================================================================
+
+let globalRegistry: Partial<XDSIconRegistry> = {};
+
+/**
+ * Register icons at the module level. Works in both server and client
+ * environments. Call once at app initialization (e.g. root layout).
+ *
+ * Icons registered here are available to all components — including
+ * server-rendered ones that can't access React Context.
+ *
+ * @example
+ * ```ts
+ * // app/layout.tsx (RSC-compatible)
+ * import { registerIcons } from '@xds/core';
+ * import { brandIcons } from './brand-icons';
+ *
+ * registerIcons(brandIcons);
+ * ```
+ */
+export function registerIcons(icons: Partial<XDSIconRegistry>): void {
+ globalRegistry = {...globalRegistry, ...icons};
+}
+
+/**
+ * Get an icon by name from the global registry, falling back to defaults.
+ *
+ * Use this in server components where hooks aren't available.
+ * In client components, prefer useXDSIcon() which also checks
+ * the React Context registry.
+ */
+export function getIcon(name: XDSIconName): ReactNode {
+ return globalRegistry[name] ?? defaultIcons[name];
+}
+
+/**
+ * Get the raw global registry (internal use by useXDSIcon).
+ * @internal
+ */
+export function getGlobalRegistry(): Partial<XDSIconRegistry> {
+ return globalRegistry;
+}
+
+/**
+ * Reset the global registry. For testing only.
+ * @internal
+ */
+export function resetIcons(): void {
+ globalRegistry = {};
+}
diff --git a/packages/core/src/Icon/index.ts b/packages/core/src/Icon/index.ts
index 642f72ade0..de547cb4ab 100644
--- a/packages/core/src/Icon/index.ts
+++ b/packages/core/src/Icon/index.ts
@@ -1,7 +1,7 @@
/**
* @file index.ts
- * @input Imports XDSIcon component/types and IconRegistry types
- * @output Exports XDSIcon, its prop types, icon registry context, and semantic name types
+ * @input Imports XDSIcon component/types, icon registry, and global registration
+ * @output Exports XDSIcon, icon registry, registerIcons, getIcon
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
* SYNC: When modified, update this header and /packages/core/src/Icon/Icon.doc.mjs
@@ -14,5 +14,10 @@ export type {
XDSIconSize,
XDSIconType,
} from './XDSIcon';
-export type {XDSIconName, XDSIconRegistry} from './IconRegistry';
-export {IconRegistryContext} from './IconRegistry';
+
+// Global registry (RSC-compatible, no 'use client')
+export {registerIcons, getIcon, resetIcons} from './globalIconRegistry';
+export type {XDSIconName, XDSIconRegistry} from './globalIconRegistry';
+
+// Context registry (client-only)
+export {IconRegistryContext, useXDSIcon} from './IconRegistry';
diff --git a/packages/core/src/theme/XDSTheme.tsx b/packages/core/src/theme/XDSTheme.tsx
index c765fdf9b5..13276f4d8d 100644
--- a/packages/core/src/theme/XDSTheme.tsx
+++ b/packages/core/src/theme/XDSTheme.tsx
@@ -30,6 +30,7 @@ import * as stylex from '@stylexjs/stylex';
import type {ThemeMode} from './types';
import {colorVars, typographyVars} from './tokens.stylex';
import {IconRegistryContext} from '../Icon/IconRegistry';
+import {registerIcons} from '../Icon/globalIconRegistry';
import {generateThemeCSS, type XDSDefinedTheme} from './defineTheme';
/**
@@ -134,10 +135,11 @@ export function XDSTheme({
? wrapperStyles.light
: wrapperStyles.system;
- // Icons
+ // Icons — register globally (for server components) AND via context (for tree-scoped overrides)
const icons = theme.icons;
let content: React.ReactNode = children;
if (icons != null) {
+ registerIcons(icons);
content = (
<IconRegistryContext.Provider value={icons}>
{content}