A single glyph from the shared iconsax set — referenced by name, never a raw <svg> hand-written in app code.
<app-icon name="download" size="18" />
An icon is a single glyph — a download arrow, a bell, a trash can — that reinforces meaning without words. <app-icon> maps a stable, portal-owned name onto the underlying iconsax glyph and renders it as an inline SVG, so call sites stay declarative (<app-icon name="download" />) and never hand-write raw icon markup.
The glyph bodies are generated from one source shared with the React AppIcon and the wui elements, so every Webority surface draws the identical icon.
Playground
Every attribute, live. Each change re-renders the real tag helper on the server, so the markup underneath is the exact call that produced the glyph above it.
No icon matches.
name accepts the whole catalogueSearch above and click a tile to preview it — or type a name straight into name (it accepts any of the 1086 names, with typeahead). An unknown name renders nothing: add it to the shared map, or register a product glyph.
Tooltip
Pass tooltip to give a glyph a hover label. It shows the same collision-aware (Bootstrap/Popper) tooltip as every other tooltip-attribute App* — flipping to stay on-screen — and wraps the icon in a .wui-icon-tip span carrying role="img" + aria-label for assistive tech. Use tooltip-placement to prefer a side.
Hover to reveal
The native title shows on hover; screen readers announce it as the icon's name.
Names are aliases, not raw glyph identifiersname is the portal's own alias (e.g. edit, trash-2), mapped to the underlying iconsax glyph in one place (scripts/icon-map.json). So if the icon set ever changes, call sites don't — you update the map, not every page.
Variants
Six iconsax styles per glyph. Linear is the library default; pass variant to pick another. An unknown variant falls back to the default body.
Pick one style per surfaceMixing variants inside one screen reads as inconsistency, not emphasis. Portals default to linear; a product that prefers a heavier look (e.g. bulk) should apply it consistently.
All icons
Every name in the shared set (1086). Type to filter; click a tile to copy its name.
Colour carries meaning — don't decorate with itReach for a tint only when it signals something (success, danger). A rainbow of decorative icon colours reads as noise and dilutes the tints that actually mean something.
In context
Icons most often reinforce a label inside another component — a button, a menu item, a list row — never floating on their own.
An icon reinforcing a button label
A button's left-icon / right-icon slot takes a glyph name, sized to match the label.
Iconsax is the library default, not a cage. A product that needs its own glyph (a brand mark, a custom SVG, another set) registers a render for a name via IconRegistry.Register, and <app-icon> resolves it before the built-in map — every unregistered name still gets the iconsax default.
Register a product glyph
Call IconRegistry.Register once at startup. A registered name wins over the built-in glyph; unregistered names still resolve normally. Below, "demo-spark" is a registered custom SVG shown beside the built-in star.
React parallel — registerIconsThe React surface has the same hook as a function: registerIcons({ name: render }). Same override mechanism, host-shaped API — so <AppIcon name="…" /> resolves a product glyph the same way. The override capability is shared; only the registration call is host-specific.
When to use
Use it when
A label needs a small visual cue to reinforce its meaning — download, search, delete.
A component slot asks for an icon node (a button, a tab, a menu item).
You want a glyph referenced by a stable name so the underlying set can change centrally.
Reach for something else when
The icon is the whole clickable control in a row or toolbar. → AppActionIcon
You need an interactive, labelled action. → AppButton
The meaning is not obvious from the glyph alone. → a text label
Best practices
Do
The icon reinforces a clear text label — it supports the word, it doesn't replace it.
Don't
Hand-written icon markup in app code bypasses the shared name map and drifts.
Do
16px glyph beside 16px text — they align.
Icon size matches the text it sits beside, so the baseline stays clean.
Don't
Oversized glyph beside body text.
A glyph far larger than its label unbalances the row and pulls the eye away from the words.
Every option
The whole surface of the component, one cell per value — sizes, variants, colour, and the resolution paths a normal example doesn't show: mapped name, the custom hard-hat SVG, and a registered override.
name="not-a-real-name" — unknown name renders nothing
name="hard-hat" — custom inline SVG, no iconsax glyph exists
name="hard-hat" color — currentColor tints the inline SVG too
name="demo-spark" — IconRegistry.Register() override wins over the built-in map
className & style — React-only passthrough
React-only — no class attribute
React-only — no inline-style attribute
className / style are React-onlyThe tag helper only exposes name, size, color and variant — there is no class/inline-style attribute, so <app-icon> always emits the same fixed glyph markup. Wrap it in an element you do control to adjust spacing or layout around it.
Attributes
Attribute
Type
Default
Description
name *
string
—
The icon name (e.g. download, trash-2). An empty or unknown name renders nothing — add it to the shared map or register a product glyph.
variant
string
linear
Iconsax style: linear, outline, bold, bulk, broken, twotone. An unknown variant falls back to the default body.
size
int
16
Glyph size in pixels (the SVG width/height).
color
string
—
CSS colour for the glyph. Omit to inherit the current text colour.
tooltip
string
—
A collision-aware hover/focus tooltip (Bootstrap/Popper, same engine as <app-tooltip>) that flips to stay on-screen. Wraps the glyph in a .wui-icon-tip span carrying role="img" + aria-label so the icon is also named for assistive tech.
tooltip-placement
string
auto
Preferred tooltip side — auto/top/bottom/start/end. auto picks the side with the most room.
className
—
—
React-only. The tag helper has no class attribute; wrap <app-icon> in an element you control to adjust layout.
style
—
—
React-only. There is no inline-style attribute on the tag helper.