Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Tooltip

Add a tooltip to an icon that stands alone, so people learn what it does on hover or focus.

Hover to reveal
Hover or focus the icon to see its tooltip; screen readers announce it too.
Show code
<app-icon name="bell" size="22" tooltip="Notifications" />

Choosing a glyph

Name each icon by its semantic name, such as bell or download, from the shared set rather than a raw identifier.

A handful of glyphs
Pass name; the component renders the matching glyph at the default 16px size.
Show code
<app-icon name="bell" />
<app-icon name="download" />
<app-icon name="check-circle" />
<app-icon name="trash-2" />
<app-icon name="settings" />
<app-icon name="search" />

Icon styles

Pick one style per surface, such as outline or bulk, and use it consistently across the screen.

One glyph, six styles
linear (default)
variant=outline
variant=bold
variant=bulk
variant=broken
variant=twotone
Show code
<app-icon name="bell" size="28" /> <!-- linear (default) -->
<app-icon name="bell" size="28" variant="outline" />
<app-icon name="bell" size="28" variant="bold" />
<app-icon name="bell" size="28" variant="bulk" />
<app-icon name="bell" size="28" variant="broken" />
<app-icon name="bell" size="28" variant="twotone" />

Sizes

Size an icon in pixels to match the text or control it sits beside, from a small badge to a large hero.

From small to large
Show code
<app-icon name="bell" size="14" />
<app-icon name="bell" size="20" />
<app-icon name="bell" size="28" />
<app-icon name="bell" size="40" />

Colour

An icon takes the text colour around it unless a tint is set, and colour must never be the only signal.

Inherited vs tinted
Left inherits the text colour; the others use color to signal success and danger.
Show code
<app-icon name="check-circle" />
<app-icon name="check-circle" color="var(--wui-success)" />
<app-icon name="trash-2" color="var(--wui-danger)" />

With a button label

Put an icon beside a label to reinforce it, never to replace the words on a button.

An icon reinforcing a button label
Pass a glyph name as the button's left-icon or right-icon, sized to match the label.
Show code
<app-button left-icon="download">Export</app-button>
<app-button variant="Outline" right-icon="arrow-right">Continue</app-button>

Overriding icons (product glyphs)

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.
registered glyph (left) vs built-in star (right)
Show code
IconRegistry.Register("demo-spark", (size, cls) => $"<svg data-icon='demo-spark' width='{size}' height='{size}' viewBox='0 0 24 24' fill='currentColor' class='{cls}'><path d='M12 2l2.4 6.6L21 11l-6.6 2.4L12 20l-2.4-6.6L3 11l6.6-2.4z'/></svg>");

<app-icon name="demo-spark" />

Every option

Every value of every prop, one cell each.

size: representative range

size="12"
size="16" (default)
size="20"
size="24"
size="32"
size="48"
size="64"

variant: all six styles

(default) linear
variant="outline"
variant="bold"
variant="bulk"
variant="broken"
variant="twotone"

colour

(inherited)
color="var(--wui-success)"
color="var(--wui-warning)"
color="var(--wui-danger)"
color="#7c3aed": any CSS colour

name: mapped, unknown, custom SVG, registered

name="download": mapped name, iconsax glyph
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

tooltip: hover and focus label

tooltip="Notifications": shown on hover or focus

tooltipPlacement: where the tooltip opens

tooltip-placement="auto" (default)
tooltip-placement="top"
tooltip-placement="bottom"
tooltip-placement="start"
tooltip-placement="end"

className & style: React-only passthrough

className: React only, Razor has no class attribute
style: React only, Razor has no inline style attribute

Guidance

What to do, and what to avoid.

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

Reinforce a text label

Do

The icon reinforces a clear text label: it supports the word and does not replace it.

Avoid

Hand-written icon markup in app code bypasses the shared name map and drifts.

Match the text size

Do
16px glyph beside 16px text, they align.

AppIcon size matches the text it sits beside, so the baseline stays clean.

Avoid
Oversized glyph beside body text.

A glyph far larger than its label unbalances the row and pulls the eye away from the words.

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

linear outline bold bulk broken twotone
auto top bottom start end
React, generated from the controls
<AppIcon name="download" />
Razor, the same props
<app-icon name="download" />

6 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
namedefault - string - Icon name (kebab-case; curated or full-catalogue).
variantdefault linear linear | outline | bold | bulk | broken | twotone linear Icon style: linear, outline, bold, bulk, broken or twotone.
sizedefault 16 int 16 Icon size in pixels.
tooltipdefault - string - A hover and focus tooltip that flips to stay on screen. The glyph is wrapped in a span with role img and an aria-label, so the icon is also named for assistive tech.
tooltip-placementdefault auto auto | top | bottom | start | end auto Preferred tooltip side; auto picks the side with the most room.

Less common 1 props

PropTypeDefaultDescription
colordefault - string - The icon colour. Without it the icon takes --wui-icon-color when an ancestor sets that variable, else the inherited text colour.

Screen reader

3 notes
  • Without a tooltip the glyph is an svg marked aria-hidden, so it is decorative and the control around it needs its own accessible name.
  • With a tooltip the glyph is wrapped in a span with role img and an aria-label set to the tooltip text, so the icon is named for assistive tech.
  • The tooltip opens on hover and on keyboard focus, through the same tooltip engine as every other tooltip prop.

Do and avoid

2 pairs

Reinforce a text label

Do

The icon reinforces a clear text label: it supports the word and does not replace it.

Avoid

Hand-written icon markup in app code bypasses the shared name map and drifts.

Match the text size

Do
16px glyph beside 16px text, they align.

AppIcon size matches the text it sits beside, so the baseline stays clean.

Avoid
Oversized glyph beside body text.

A glyph far larger than its label unbalances the row and pulls the eye away from the words.