Props

Name	Type	Default	Description
name	string	—	Iconify id, collection:icon. carbon-settings is the same as carbon:settings after the carbon collection is registered. Hyphenated collection names should keep the colon.
icon	string | Component	—	A semantic name, a CSS icon class, or your own component. A semantic name resolves to an Iconify id from the nearest theme, and falls back to the built-in glyph until that icon is registered. Ignored when name is set.
color	'inherit' | 'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'blue' | 'cyan' | 'green' | 'gray' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'	'inherit'	Sets the color the icon's currentColor resolves to. inherit keeps the surrounding text color.
size	'xsm' | 'sm' | 'md' | 'lg'	—	12px, 16px, 20px, or 24px at a 16px root. When omitted, a name icon is 1em. Any other icon falls back to md unless a parent provides a size.
label	string	—	Accessible name for a meaningful icon. Sets role="img" and aria-label. Omit it for decoration (aria-hidden="true"). An empty string stays decorative.

Slots

• Default: SVG written inline, used when neither name nor icon is set.

Registration

Name	From	Description
astryxIcons()	@astryx-vue/core/icons	Vite plugin. Scans static names and bundles only those icons from installed @iconify-json/* packages. Pass collections to limit which prefixes are read.
addIcon(name, data)	@astryx-vue/core/Icon	Register one icon. name is collection:icon. data.body is the SVG inner markup.
addCollection(collection)	@astryx-vue/core/Icon	Register an @iconify-json document. The whole collection is included in the bundle.

Semantic names

defineTheme({ icons }) overrides by name. Entries merge shallowly with the theme this one extends, and this theme wins. A name that is not listed keeps the default id. The collection has to be registered, or the built-in glyph stays.

Name	Default Iconify id
close	lucide:x
chevronDown	lucide:chevron-down
chevronLeft	lucide:chevron-left
chevronRight	lucide:chevron-right
chevronsLeft	lucide:chevrons-left
chevronsRight	lucide:chevrons-right
check	lucide:check
success	lucide:circle-check
error	lucide:circle-x
warning	lucide:triangle-alert
info	lucide:info
calendar	lucide:calendar
clock	lucide:clock
externalLink	lucide:external-link
menu	lucide:menu
moreHorizontal	lucide:ellipsis
search	lucide:search
upload	lucide:upload
arrowUp	lucide:arrow-up
arrowDown	lucide:arrow-down
arrowsUpDown	lucide:arrow-up-down
funnel	lucide:funnel
eyeSlash	lucide:eye-off
viewColumns	lucide:columns-3
copy	lucide:copy
checkDouble	lucide:check-check
wrench	lucide:wrench
stop	lucide:square
microphone	lucide:mic
image	lucide:image

These are the shared names. Every component draws from the same set. The IconRegistry type describes a complete registry that draws every shared name, and upload is required like the rest. A theme that supplies a whole icon set must give upload its own upload drawing instead of reusing arrowUp. Redrawing upload leaves the arrowUp used by sortable tables and the send button alone.

An icon that only one component draws does not become a shared name. It gets a namespaced key, component:role, typed as NamespacedIconName. There is one today:

Key	Used by
numberInput:stepperDown	NumberInput's step buttons. A small down chevron; the increment button flips it.

A theme overrides it through the same icons map: defineTheme({ icons: { 'numberInput:stepperDown': 'carbon:chevron-down' } }). Without an override the built-in glyph is drawn. Adding a namespaced key never adds a required entry to IconRegistry.

useSemanticIcon(name) comes from @astryx-vue/core/Icon and from the package root. An unknown string with no theme entry returns empty, so the caller can still treat it as a CSS class.

Theme

Color follows the icon tokens. A theme replaces one by setting the variable on the theme root.

.my-theme {
  --astryx-icon-accent-foreground: #0074e2;
}

• --astryx-icon-primary-foreground
• --astryx-icon-secondary-foreground
• --astryx-icon-disabled-foreground
• --astryx-icon-accent-foreground
• --astryx-icon-success-foreground
• --astryx-icon-error-foreground
• --astryx-icon-warning-foreground
• --astryx-icon-blue-foreground, and the same pattern for cyan, green, gray, orange, pink, purple, red, teal, and yellow.

Accessibility

The root is a <span>. Without label it is aria-hidden="true". With a non-empty label it is role="img" and that string is the accessible name. The SVG inside is always aria-hidden.

class and style fall through to the root. name does not: it selects the icon.