Icon
IconSVG symbol A small visual cue with a precise purpose. Registered SVG symbols follow the surrounding text color.
Layout & contentIn context
Decorative icons are hidden from assistive technology when the adjacent label supplies the meaning.
<div class="component-recipe">
<Flex direction="column">
<Flex align="center">
<Icon name="lucide:layers" aria-hidden="true"/>
<h3>Project library</h3>
</Flex>
<Flex align="center">
<Icon name="lucide:check" aria-hidden="true"/>
<span>All checks passed</span>
</Flex>
<BtnLink href="/guides/" variant="outline">
<Flex inline="true" align="center">
<span>Explore the guides</span>
<Icon name="lucide:arrow-right" aria-hidden="true"/>
</Flex>
</BtnLink>
</Flex>
</div> Icons alongside text
Decorative symbols support visible labels without repeating them to assistive technology.
<Flex wrap="true" align="center">
<Flex align="center">
<Icon name="lucide:check" aria-hidden="true" />
<span>Checks passed</span>
</Flex>
<Flex align="center">
<Icon name="lucide:mail" aria-hidden="true" />
<span>Inbox</span>
</Flex>
</Flex> A standalone symbol
When an icon is the only content, provide its meaning on a semantic wrapper.
<span role="img" aria-label="Checks passed" class="fs-h2">
<Icon name="lucide:check" aria-hidden="true" />
</span> Symbols with a purpose
A few verified symbols from the registry. Icon has one prop, name; size and color come from ordinary attributes and CSS.
lucide:layers lucide:layout-grid lucide:check lucide:settings lucide:star lucide:arrow-right Every value is visible. Compare treatments in the site’s light and dark themes.
Size and inherited color
These are CSS choices, not Icon props. The same symbol inherits each container’s font size and currentColor.
sm md lg Every value is visible. Compare treatments in the site’s light and dark themes.
Missing and decorative icons
An omitted or unresolved name produces no icon element. A missing symbol should never be the only way to understand an action. Put aria-hidden="true" on decorative icons; use role="img" and a meaningful aria-label for a standalone symbol.
<Icon name="lucide:check" aria-hidden="true"/>
<Icon name="lucide:star" role="img" aria-label="Featured project"/>
<Icon/> Behavior and accessibility
The component renders no output for an empty or unresolved icon name. Icon does not supply button semantics. Put actions in Btn and give icon-only controls an ariaLabel.
API reference
Icon contract
Props below are the public template API. RefOrValue accepts a literal or a reactive ref; bind refs with a colon-prefixed attribute. Native attributes and events can be passed through the component root.
name
RefOrValue<string> - Default
not set
Exact registered icon name, including its collection prefix, for example lucide:check. The icon resolver returns trusted SVG markup.
Composition
No slots. Register defineIconComponents with a resolver returning SVG markup for the icons your app uses. SSG already provides its icon registry.
Browser registration
import { defineIconComponents } from '@purestack/ts-components'
import { lucide_check } from '@purestack/ts-svg-icons'
const icons: Record<string, string> = { 'lucide:check': lucide_check }
const components = defineIconComponents((name) => icons[name] ?? '')