Icons

Components that accept an icon prop use IconType: either a semantic name string or a direct SVG component. The semantic names below are resolved through the global icon registry.

For icons not in the semantic list, pass an SVG component directly. Any ComponentType<SVGProps<SVGSVGElement>> works; Icon applies size and color styling automatically.

tsx
import { PhotoIcon } from '@heroicons/react/24/outline';
import { HeartIcon } from 'lucide-react';
​
<Icon icon={PhotoIcon} size="lg" />
<Icon icon={HeartIcon} color="error" />

Themes can replace the default SVGs for any semantic name with the icons field in defineTheme(). This lets you swap the icon set (e.g. heroicons → lucide) without touching component code, and keeps lookup scoped to the active theme instead of mutating global defaults.

tsx
import {defineTheme} from '@astryxdesign/core/theme';
import {XMarkIcon, ChevronDownIcon} from '@heroicons/react/24/outline';
​
export const brandTheme = defineTheme({
  name: 'brand',
  icons: {
    close: <XMarkIcon />,
    chevronDown: <ChevronDownIcon />,
  },
});

An entry can also be a function of the request, so the theme maps Icon's size to its icon library's own props or artwork. Icon calls it with {size, variant}, where size is the size it renders at (xsm, sm, md, or lg: an explicit size, else the owning component's default, else md). Reads that return one node — getIcon(), useIcon(), getIconRegistry(), and the theme's icons field — call it with {size: 'md'}. The same entry shape works in registerIcons().

tsx
import {defineTheme} from '@astryxdesign/core/theme';
import {Info} from 'lucide-react';
​
export const brandTheme = defineTheme({
  name: 'brand',
  icons: {
    // A heavier stroke keeps the small size legible.
    info: ({size}) => <Info strokeWidth={size === 'sm' || size === 'xsm' ? 2.5 : 2} />,
  },
});

Keep the function pure and synchronous: it computes its result from the request only, with no hooks, DOM or SVG measurement, browser globals, network access, mutable module state, or side effects. Its result is final. Returning null draws no glyph instead of falling back to a registered or built-in icon, while a null or undefined node entry still falls back. A child theme that sets an entry for a key replaces the inherited entry for that key.

A glyph that belongs to one component or library gets a namespaced key (numberInput:stepperDown, richtext:bold) instead of a new semantic name. It resolves through the same registry and a theme overrides it the same way, but the shared IconName list stays reserved for glyphs the whole system uses, so adding one does not make every downstream icon registry grow a key.

tsx
// The component renders it like any other name, keeping size and color.
<Icon icon="numberInput:stepperDown" size="xsm" />
​
// A theme maps it independently of the shared chevron.
export const brandTheme = defineTheme({
  name: 'brand',
  icons: {
    chevronDown: <ChevronDownIcon />,
    'numberInput:stepperDown': <CaretDownFilledIcon />,
  },
});

Outside core, pass a fallback to getExtendedIcon(key, fallback) so the glyph renders with no theme.