Icon

Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Icon

Prop	Type	Default	Description
icon *	IconName \| ComponentType<SVGProps>		Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.
color	'primary' \| 'secondary' \| 'tertiary' \| 'disabled' \| 'accent' \| 'success' \| 'error' \| 'warning' \| 'inherit'	'inherit'	Color variant mapped to Astryx icon color tokens.
size	'xsm' \| 'sm' \| 'md' \| 'lg'	Contextual; otherwise 'md'	Icon size. An explicit value wins. When omitted, Icon uses the nearest default supplied by an owning Astryx component for its icon slot, then falls back to md when no contextual default exists.
label	string		Accessible name for a MEANINGFUL, standalone icon (a status glyph or icon-only indicator with no adjacent text). Setting it exposes the icon to screen readers as role="img" with this text as the accessible name (aria-label) and removes the default aria-hidden. Omit it (default) for decorative icons and the icon stays hidden from assistive tech (aria-hidden="true"). This is the accessible-name / alt-text prop for icons: one prop instead of manually setting aria-label + role + aria-hidden. An empty string is treated as decorative. Do not set it when an interactive parent (Button, IconButton, link) already names the control.
xstyle	StyleXStyles		StyleX styles for customization (color, size, opacity). Folded into the icon's own stylex.props() call so it composes with the base color/size styles. Must be a stylex.create() value, not an inline style object like style={{}}.

Usage guidance

Use semantic icon names when available; they adapt to theme changes automatically.
Override icons through the theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>, and extends shallow-merges it into derived themes. registerIcons() mutates a process-wide registry and warns in dev, so keep it for app bootstrap rather than making it a library's theming seam.
Pair icons with text labels for accessibility; icon-only elements need an accessible label.
For a meaningful standalone icon (no adjacent text), give it an accessible name via the label prop: it sets role="img" + aria-label and unhides the icon.
Use color tokens for icon colors, not hardcoded hex values.
Be mindful of context; decorative icons in compact components can distract rather than help.
Avoid: Use icons as the sole means of conveying meaning; always provide a text alternative.
Avoid: Resize icons with arbitrary pixel values; use the provided size props.
Avoid: Mix icon styles (e.g. outline and filled) within the same context.
Avoid: Render raw SVG elements; always wrap in Icon for consistent sizing and color.
Avoid: Pass a name prop; Icon uses icon (not name) to specify which icon to render.

Theming API

{
  "targets": [
    {
      "className": "astryx-icon",
      "visualProps": [
        "color",
        "size"
      ]
    }
  ]
}

Anatomy

Glyph: Visual symbol rendered for the selected icon.

Examples

Icon:
Icon — Non-Semantic Colors: Non-semantic color palette for icons.
Icon — Semantic Colors: All semantic icon color variants with labels.
Icon — Size Variants: All icon sizes from extra-small to large.
Icon — Status Indicators: Status list using semantic icons for success, warning, error, and info.