Icon·component·@astryxdesign/core

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.

Open in Playground @astryxdesign/core/Icon

Showcases and examples

5 documented examples

Icon

Icon API entry

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · icon-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {Icon} from '@astryxdesign/core/Icon';

export default function IconShowcase() {
  return <Icon icon="search" color="primary" size="md" />;
}

Usage

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.
Use icons as the sole means of conveying meaning; always provide a text alternative.
Resize icons with arbitrary pixel values; use the provided size props.
Mix icon styles (e.g. outline and filled) within the same context.
Render raw SVG elements; always wrap in Icon for consistent sizing and color.
Pass a name prop; Icon uses icon (not name) to specify which icon to render.

Typed props

Prop	Type and behavior
`icon`	`IconName \| ComponentType<SVGProps>` · required 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, 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'` · default 'inherit' Color variant mapped to Astryx icon color tokens.
`size`	`'xsm' \| 'sm' \| 'md' \| 'lg'` · default 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={{}}.

Anatomy

Glyph · required

Visual symbol rendered for the selected icon.

Theming

Targets

astryx-icon

Visual props: color, size