GUILD OF GLEKS UIv21.19.0

gog-spinner

Spinner

A branded loading indicator with two built-in animated variants, fully custom-content support, size variants, per-instance color and speed overrides, and both a content-scoped and a full-screen overlay mode.

Overview

Import the component and drop it into a template.

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

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

Basic usage — a spinner named for what is loading:

<gog-spinner ariaLabel="Loading invoices" />

Examples

Sizes and variants

runic is the default and the library's own; ring is the plain one. custom projects your markup into the same size box, so it scales like the other two — the third column projects an SVG that animates without a stylesheet. Under prefers-reduced-motion the built-ins stop moving and stay drawn; a custom one is yours to stop.

size: xsm
size: sm
size: md
size: lg
size: slg
@for (size of sizes; track size) {
  <div>
    <span>size: {{ size }}</span>
    <gog-spinner [size]="size" ariaLabel="Loading" />
    <gog-spinner [size]="size" variant="ring" ariaLabel="Loading" />
    <!-- custom: your markup in the same size box. This one animates with SVG, no stylesheet. -->
    <gog-spinner [size]="size" variant="custom" ariaLabel="Loading">
      <svg viewBox="0 0 24 24" width="100%" height="100%" style="fill: var(--gog-accent-color)">
        @for (x of [4, 12, 20]; track x; let i = $index) {
          <circle [attr.cx]="x" cy="12" r="3">
            <animate
              attributeName="opacity"
              values="0.2;1;0.2"
              dur="1s"
              [attr.begin]="i * 0.15 + 's'"
              repeatCount="indefinite"
            />
          </circle>
        }
      </svg>
    </gog-spinner>
  </div>
}

Animation speed

--gog-spinner-spin-duration (and -pulse-duration for the rune glow) retime the built-in animations per instance without swapping variant — to signal urgency, or to match a surrounding motion rhythm.

<gog-spinner size="lg" style="--gog-spinner-spin-duration: 2.4s" ariaLabel="Loading, slow" />
<gog-spinner size="lg" ariaLabel="Loading" />
<gog-spinner size="lg" style="--gog-spinner-spin-duration: 0.5s" ariaLabel="Loading, fast" />

Colour

The spinner draws in the accent colour. On a surface where the accent does not read — a danger banner, a filled button — set --gog-spinner-color on it or an ancestor.

<gog-spinner style="--gog-spinner-color: var(--gog-danger-color)" ariaLabel="Retrying" />
<gog-spinner
  variant="ring"
  style="--gog-spinner-color: var(--gog-success-color)"
  ariaLabel="Uploading"
/>

The app's own indicator, everywhere at once

Most of the spinners an app shows are not ones it writes: gog-button draws one while loading, gog-autocomplete while it searches, gog-table in place of its rows, gog-spinner-overlay over a region — none take a spinner input. GOG_CONFIG.spinner.component gives them your look: pass a component, and every spinner the library draws renders it inside its own size box, keeping the sizing and the accessible name. Here a pulsing skeleton bone stands in for your loader, so the example carries no stylesheet. An instance's own variant still wins; GOG_CONFIG.spinner.variant is the lighter key, choosing between runic and ring app-wide. See Global Configuration.

<gog-spinner size="lg" ariaLabel="Loading" />
<!-- No spinner input at all: the button draws the configured component too. -->
<gog-button [loading]="saving()" (gogClick)="save()">Save</gog-button>
<!-- An instance that asks for something specific still wins. -->
<gog-spinner size="lg" variant="ring" ariaLabel="Loading" />

Covering a region

gog-spinner-overlay

Lays a scrim and a spinner over its own content while loading is on, and marks the region aria-busy. The content stays rendered underneath, so nothing jumps when loading ends. The scrim stops the pointer and the content is inert21.15.0, so Tab skips it too; focus that was inside — press Export, then load — waits on the spinner and comes back when loading ends. It forwards variant, size and ariaLabel to its spinner.

Twelve invoices, three overdue.

<!-- The content stays rendered underneath, and is inert while loading. -->
<gog-spinner-overlay [loading]="loading()" ariaLabel="Loading invoices">
  <gog-panel>
    <p>Twelve invoices, three overdue.</p>
    <gog-button variant="outline" size="sm">Export</gog-button>
  </gog-panel>
</gog-spinner-overlay>
<gog-button variant="outline" size="sm" (gogClick)="load()">Load for 3s</gog-button>

The whole viewport

overlay on gog-spinner itself covers the viewport, for a load that blocks the whole app. "The viewport" holds only while no ancestor creates a containing block: a transform, filter or contain above it retargets the overlay to that element, so render it near the app's root. On this site it covers the content area rather than the window — that area is a gog-scroll, which sets contain: layout style.

<gog-button variant="outline" size="sm" (gogClick)="cover()">Cover the page for 1.5s</gog-button>
<!-- Behind a flag that ends on its own: it swallows every click while it is up. -->
@if (covering()) {
  <gog-spinner overlay size="lg" ariaLabel="Loading page" />
}

Accessibility

An indeterminate progress bar named by ariaLabel. It does not announce itself — the region that is busy does, with aria-busy.

  • Role and name — role="progressbar" with no value, the pattern for "working, no idea how long", named by ariaLabel21.15.0. Name it for what is loading when more than one thing can be; ariaLabel="" makes it decorative.
  • Inside a loading gog-button it is aria-hidden, because the button already says it is busy.
  • Regions — gog-spinner-overlay sets aria-busy on the region it covers and makes its content inert while loading.
  • Keyboard — none. A spinner is not focusable.

API Reference

gog-spinner — Inputs

NameTypeDefaultDescription
variant'runic' | 'ring' | 'custom'unsetrunic and ring are built-in presets. custom renders your own markup via content projection — it inherits the size wrapper, overlay behavior, and --gog-spinner-color theming, but the visuals are yours. Left unset, this falls through to GOG_CONFIG.spinner.component, then to GOG_CONFIG.spinner.variant, then to runic.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg''md'Wrapper and glyph size.
overlaybooleanfalseRenders as a fixed, viewport-covering overlay. Distinct from gog-spinner-overlay below, which only covers its own content.
ariaLabelstring'Loading'Names the spinner, which is an indeterminate role="progressbar" — read as progressbar "Loading". ariaLabel="" makes it decorative: no role, no name. Before 21.15.0 the input was accepted and never rendered, so every spinner was invisible to assistive tech.

gog-spinner-overlay — Inputs

NameTypeDefaultDescription
loadingbooleanfalseShows a scrim + spinner over the projected content while true.
variant'runic' | 'ring' | 'custom' | undefinedunsetForwarded to the inner gog-spinner, and unset by default so that "asked for nothing" survives the trip: an overlay that names no variant lets GOG_CONFIG.spinner.component or .variant through, exactly as a bare gog-spinner does. It defaulted to runic until 21.10.0, which the inner spinner read as an explicit request — so a configured house spinner appeared everywhere except here.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg''md'Forwarded to the inner gog-spinner.
ariaLabelstring'Loading'Forwarded to the inner gog-spinner.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.spinner.component — your own component drawn in place of the built-in look, everywhere the library’s spinner appears — an instance’s own variant still wins over it. gog-spinner-overlay forwards a variant of its own, but only when one is set: it honours this key from 21.10.0 on.
  • GOG_CONFIG.spinner.variant — the app-wide preset an instance that asks for none gets

Styling Tokens

Every CSS custom property the spinner 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-spinner-track-colorBackground ring.
--gog-spinner-arc-outer-color / -arc-inner-colorSpinning arc colors.
--gog-spinner-diamond-color / -rune-color / -glow-colorDecorative elements on the larger spinner variants.
--gog-spinner-spin-duration / -pulse-durationAnimation timing.