GUILD OF GLEKS UIv21.19.0

gog-icon

Icon

A thin wrapper around the library's built-in SVG set — and, since 21.4.0, around your own as well: register any SVG under a name and it works everywhere a built-in one does. Small on its own, but every other component that needs an icon (button, checkbox, dialog, input field…) renders through it.

Overview

Import the component and drop it into a template.

typescript
import { IconComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [IconComponent],
})

Basic usage — one of the built-in icons by name, beside the text it illustrates:

Saved
<span><gog-icon name="check" /> Saved</span>

Examples

The built-in set

Every GogBuiltinIconName, read off ICON_DEFS rather than typed in, so the list cannot fall behind the package: 136 glyphs, up from 41 before 21.19.0 — navigation and layout, actions, files and media, communication, people and status, commerce and data, and appearance (sun, moon, monitor). The registry ships whole, so all 136 cost an app about 6.3 KB gzipped whichever it uses. All of them are Lucide glyphs (ISC licence, notice shipped in the package) on one 24×24 grid, drawn with currentColor and inlined — no icon font and no runtime dependency. The set is outline-only apart from two pairs, checkbox / checkbox-checked and star / star-filled, which exist for a toggle that has to show both states; anything else is registered by the app.

Chevrons & arrows

chevron-up
chevron-down
chevron-left
chevron-right
arrow-left
arrow-right

Confirm & dismiss

check
close
checkbox
checkbox-checked

Status

success
error
warning
info

Sorting

sort
sort-up
sort-down
filter

Actions

search
plus
minus
trash
pencil
copy
download
upload
refresh
external-link

Chrome

menu
more-horizontal
more-vertical
settings

Objects & state

user
lock
mail
calendar
clock
eye
eye-off
star
star-filled

Navigation & layout

home
arrow-up
arrow-down
arrow-up-right
chevrons-left
chevrons-right
chevrons-up-down
log-in
log-out
grid
list
dashboard
layers
sliders
drag
maximize
minimize
zoom-in
zoom-out

More actions

save
share
link
send
printer
archive
bookmark
flag
pin
undo
redo
clipboard
power

Files & media

file
file-text
folder
folder-open
paperclip
image
camera
video
mic
play
pause
volume
volume-off
cloud
database
code
terminal

Communication

bell
bell-off
message
inbox
phone
at-sign
globe
map-pin

People & status

users
user-plus
heart
thumbs-up
thumbs-down
help
ban
shield
shield-check
key
unlock
history
hourglass
zap
sparkles
lightbulb

Commerce & data

shopping-cart
credit-card
wallet
tag
gift
package
truck
building
briefcase
percent
chart-bar
chart-pie
trending-up
trending-down
activity

Appearance & devices

sun
moon
monitor
smartphone
wifi
wifi-off
book-open
@for (group of groups; track group.title) {
  <p>{{ group.title }}</p>
  @for (name of group.names; track name) {
    <div>
      <gog-icon [name]="name" />
      <code>{{ name }}</code>
    </div>
  }
}

Size and stroke from the context

--gog-icon-size is 1.2em, so an icon follows the font size of whatever it sits in — an icon in a heading is a heading-sized icon without anyone passing a size. The stroke width is --gog-icon-stroke-width, in the glyph's own units, so it stays proportional as the icon scales and a thin set is one token away.

font-size: 12px stroke 1 stroke 2 stroke 3
font-size: 16px stroke 1 stroke 2 stroke 3
font-size: 24px stroke 1 stroke 2 stroke 3
<!-- Neither is an input: the icon takes both from where it is placed. -->
@for (size of fontSizes; track size) {
  <div>
    <span>font-size: {{ size }}</span>
    @for (stroke of strokeWidths; track stroke) {
      <span [style.font-size]="size" [style.--gog-icon-stroke-width]="stroke">
        <gog-icon name="settings" /> stroke {{ stroke }}
      </span>
    }
  </div>
}

An explicit size

There is no size input. Set --gog-icon-size on the instance — or on a subtree, or in a theme — when the icon should not follow the text.

<gog-icon name="success" style="--gog-icon-size: 16px" />
<gog-icon name="success" style="--gog-icon-size: 24px" />
<gog-icon name="success" style="--gog-icon-size: 40px" />

Colour

There is no color input either: the glyph strokes with currentColor, so it takes the colour of the text around it — a status colour, a link, a muted label.

Saved Failed A link Read-only
<!-- The glyph strokes with currentColor: it takes the colour of the text around it. -->
<span style="color: var(--gog-success-color)"><gog-icon name="success" /> Saved</span>
<span style="color: var(--gog-danger-color)"><gog-icon name="error" /> Failed</span>
<a href="#overview"><gog-icon name="external-link" /> A link</a>
<span style="color: var(--gog-muted-text-color)"><gog-icon name="lock" /> Read-only</span>

Decorative or named

Icons are aria-hidden by default, since they almost always repeat the text beside them. For a standalone icon that carries meaning on its own, set [ariaHidden]="false" and a title: it becomes role="img" named by it 21.15.0. As the only content of a button, leave the icon decorative and name the button with ariaLabel.

Disk almost full
<!-- Beside text: decorative, the default. -->
<span><gog-icon name="warning" /> Disk almost full</span>
<!-- Carrying meaning no text repeats: role="img", named by title. -->
<gog-icon name="warning" [ariaHidden]="false" title="Warning" />
<!-- The only content of a button: name the button, not the icon. -->
<gog-button variant="ghost" ariaLabel="Settings"><gog-icon name="settings" /></gog-button>

A one-off template

template replaces the SVG entirely and wins over name outright. It costs an <ng-template> at every use site, so it is for the single glyph that has no business in a shared set; anything used twice belongs in provideGogIcons.

<gog-icon name="user" style="--gog-icon-size: 40px" />
<!-- template wins over name outright; the registry is never consulted. -->
<gog-icon name="user" [template]="initials" style="--gog-icon-size: 40px" />
<ng-template #initials><strong>GG</strong></ng-template>

An unknown name

The icon asks for rokcet. It renders an empty host and, in dev mode, logs the one console warning below per name — not one per instance, so a typo inside an @for of a thousand rows is one line. It never throws: an icon is decoration, and taking a page down over a misspelt glyph would be the worse failure.

html
<span>[<gog-icon name="rokcet" />] rendered here</span>
<!-- renders: [] rendered here — an empty host, no glyph -->
text
[gog-icon] No icon named "rokcet". Register it with provideGogIcons({ 'rokcet': '<svg…>' }), or use one of the built-ins.

Your own icons

name is not a closed list. It is typed GogIconName = GogBuiltinIconName | (string & {}): the built-ins autocomplete, and any name you have registered is accepted. Register once, at the root or in any injector below it:

typescript
// app.config.ts — register once, use the name anywhere an icon name is taken
import { provideGogIcons } from '@guildofgleks/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideGogIcons({
      cart: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>',
      rocket: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>',
    }),
  ],
};

Used by name, everywhere

A registered name works anywhere an icon name is taken — gog-icon itself, wherever it is placed, and the iconName inputs of components such as the tag and the chip — with no <ng-template> at the use site. That is why a registry beats the template input for an icon set.

In basket
Deploying
<!-- Asked for by name, with no <ng-template> anywhere. -->
<gog-icon name="cart" />
<gog-icon name="rocket" />
<gog-tag variant="info" iconName="cart">In basket</gog-tag>
<gog-chip iconName="rocket">Deploying</gog-chip>
<gog-button><gog-icon name="rocket" /> Launch</gog-button>

A registration wins over a built-in, and a nested one layers on

The second group sits under a directive that calls provideGogIcons again with one icon named copy. Inside it, copy is the registered glyph — that is how an app swaps the library's checkmark or chevrons everywhere at once, with no call site touched — while cart, registered above it, is still there: a nested registration adds to its parent's set rather than replacing it, the same as provideGogConfig.

outer registration

copy cart

nested provideGogIcons

copy cart
<div>
  <p>outer registration</p>
  <span><gog-icon name="copy" /> copy</span>
  <span><gog-icon name="cart" /> cart</span>
</div>
<!-- Inside, copy is the registered glyph, and cart from the outer set is still there. -->
<div appNestedIcons>
  <p>nested provideGogIcons</p>
  <span><gog-icon name="copy" /> copy</span>
  <span><gog-icon name="cart" /> cart</span>
</div>

Write the SVG for inheritance — and only markup you wrote

  • Give it a viewBox and stroke="currentColor" (or fill), and no width or height — gog-icon drives size and stroke width from the --gog-icon-* tokens, so a registered icon scales and colours exactly like a built-in.
  • Security. Registered markup is inserted with bypassSecurityTrustHtml, because Angular's HTML sanitizer strips SVG. That is safe for static markup you authored or imported at build time, and unsafe for anything derived from user input or fetched at runtime. For remote icons, fetch them yourself, run them through a real SVG sanitizer, and register the result.

Accessibility

Decorative by default: an icon usually repeats the text beside it, and announcing both says everything twice.

  • Default — aria-hidden="true" on the host. Beside text, there is nothing to do.
  • Named — [ariaHidden]="false" makes it role="img", named by title or else by the icon's name. A name like more-vertical is rarely what a person should hear, so set the title. Written as a plain attribute, title also lands on the host as the HTML title, so the browser shows it as a tooltip on hover.
  • In a button — when the icon is a button's only content, keep it decorative and name the button (ariaLabel on gog-button): the name then belongs to the thing that is pressed, and a screen reader says it once.
  • Keyboard — none. An icon is never focusable.

API Reference

Inputs

NameTypeDefaultDescription
nameGogIconName'close'A built-in glyph, or any name registered through provideGogIcons(). Ignored when template is set.
templateTemplateRef<unknown> | nullnullReplaces the SVG entirely with your own markup. For one-offs — for a whole icon set, register the names instead.
titlestring''Accessible label used when ariaHidden is false. Falls back to name if empty.
ariaHiddenbooleantrueIcons are decorative by default and hidden from assistive tech. Set false for a standalone icon that carries its own meaning (with no adjacent text label): it becomes role="img", named by title or else name. Before 21.15.0 it got the label without the role, which Chrome exposes as an unnamed generic.

Providers & tokens

NameTypeDefaultDescription
provideGogIcons(icons)Record<string, string> => Provider—Registers raw <svg> markup by name, app-wide or in any injector below it. A nested call layers onto the parent set rather than replacing it.
GOG_ICONSInjectionToken<Readonly<Record<string, string>>>{}The token provideGogIcons writes to. Inject it to read the registered set; you rarely need it directly.

Global Configuration

This component has no GOG_CONFIG entries of its own — every default is set per instance. See Global Configuration for what does apply app-wide.

Styling Tokens

Every CSS custom property the icon paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-icon-sizeDefault icon size.
--gog-icon-stroke-widthStroke width for outline icons.
--gog-icon-fallback-sizeSize used when no size is set.