GUILD OF GLEKS UIv21.19.0

gog-skeleton

Skeleton

A placeholder bone that mirrors the shape of content still loading — text lines, avatars, images, cards — so the layout holds still and the user never stares at a blank screen.

Overview

Import the component and drop it into a template.

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

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

Basic usage — three stacked text lines:

<gog-skeleton shape="text" [lines]="3" />

Examples

Shapes and sizes

text is a line at the height of that size's text, circle an avatar, rect a media block. text and rect fill their container's width, which is why every bone here sits in a cell of its own.

xsm · text

xsm · circle

xsm · rect

sm · text

sm · circle

sm · rect

md · text

md · circle

md · rect

lg · text

lg · circle

lg · rect

slg · text

slg · circle

slg · rect

<!-- text and rect fill their container's width; each cell here is one. -->
@for (size of sizes; track size) {
  @for (shape of shapes; track shape) {
    <div>
      <gog-skeleton [shape]="shape" [size]="size" />
      <p>{{ size }} · {{ shape }}</p>
    </div>
  }
}

Animations

pulse (the default) fades the bones in and out, wave sweeps a highlight across them, none holds still — for a surrounding UI that is already busy. Under prefers-reduced-motion both animations stop, whatever the input says.

pulse · text

pulse · circle

pulse · rect

wave · text

wave · circle

wave · rect

none · text

none · circle

none · rect

@for (animation of animations; track animation) {
  @for (shape of shapes; track shape) {
    <div>
      <gog-skeleton [shape]="shape" [animation]="animation" [lines]="2" />
      <p>{{ animation }} · {{ shape }}</p>
    </div>
  }
}

Lines

lines stacks bars with the theme's spacing between them, and past one line the last is shorter — the silhouette a real paragraph leaves.

[lines]="1"

[lines]="2"

[lines]="4"

@for (count of lineCounts; track count) {
  <div>
    <gog-skeleton [lines]="count" />
    <p>[lines]="{{ count }}"</p>
  </div>
}

Width, height and corners

width and height take any CSS length, to match the thing that will replace the bone. A circle given only a width stays a circle. height is ignored on text, whose line height comes from size. [rounded]="false" squares the corners for content that has square ones.

width="8rem"

circle, width="4rem"

height="6rem" [rounded]="false"

<div>
  <gog-skeleton shape="text" width="8rem" [lines]="2" />
  <p>width="8rem"</p>
</div>
<div>
  <!-- A circle given only a width stays a circle. -->
  <gog-skeleton shape="circle" width="4rem" />
  <p>circle, width="4rem"</p>
</div>
<div>
  <gog-skeleton shape="rect" height="6rem" [rounded]="false" />
  <p>height="6rem" [rounded]="false"</p>
</div>

Composed — a card that loads

A screen loads a layout, not a shape: an avatar, a title, a paragraph, a picture. Built from bones the size of what replaces them, the card keeps its height while it loads — 284px loading against 289px loaded here, in the default theme — so what is below it barely moves when the content lands. The part that needs matching by hand is the paragraph: it wraps to three lines, so its bone has [lines]="3". A bone's line height comes from its size, not from your font — count the lines and measure. The card reloads for two seconds on demand.

<!-- aria-busy on the container is what tells a screen reader the area is changing. -->
<gog-card [attr.aria-busy]="loading()">
  @if (loading()) {
    <div style="display: flex; align-items: center; gap: 12px">
      <gog-skeleton shape="circle" size="lg" ariaLabel="Loading profile" />
      <gog-skeleton shape="text" size="lg" width="10rem" />
    </div>
    <!-- The paragraph wraps to three lines, so its bone has three. -->
    <gog-skeleton shape="text" [lines]="3" />
    <gog-skeleton shape="rect" height="8rem" />
  } @else {
    <div style="display: flex; align-items: center; gap: 12px">
      <img [src]="avatar" alt="" width="48" height="48" />
      <strong>Ada Lovelace</strong>
    </div>
    <p>
      Wrote the first published algorithm for a machine that had not yet been built, and argued it
      could do more than arithmetic.
    </p>
    <gog-panel variant="outlined" style="height: 8rem">Analytical Engine, Note G</gog-panel>
  }
</gog-card>
<gog-button variant="outline" size="sm" [disabled]="loading()" (gogClick)="reload()">
  Reload for 2s
</gog-button>

Accessibility

Decorative by default: a loading page can carry dozens of bones, and each one speaking would be noise.

  • Default — a bone is aria-hidden.
  • One named bone — give ariaLabel to the one that stands for the whole loading area, and it becomes an indeterminate role="progressbar" with that name 21.19.0 — the role a spinner takes, so a loading area reads "progress bar, Loading profile" whichever of the two draws it. That makes the area findable while reading; it does not announce anything when it appears. Before 21.19.0 it was role="status", a live region with no text to speak, so nothing that used to be said is lost.
  • The container — what tells a screen reader the area is changing is aria-busy on the container, as the composed card sets, and what tells it the content has arrived is the content.
  • Keyboard — none. A skeleton is not focusable.
  • Skeleton or spinner — a skeleton when the layout of what is coming is known, so the page does not jump when it lands; a spinner when it is not, or when the wait belongs to an action rather than to content.

API Reference

Inputs

NameTypeDefaultDescription
shape'text' | 'circle' | 'rect''text'text for lines of copy, circle for avatars, rect for images or media blocks.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg''md'Line thickness, circle diameter, and default rect height.
animation'pulse' | 'wave' | 'none''pulse'pulse fades opacity, wave sweeps a shimmer highlight, none holds a static tone — useful under prefers-reduced-motion or when the surrounding UI is already busy.
widthstring | nullnullCSS width, e.g. '240px' or '60%'. Falls back to a shape/size default when unset.
heightstring | nullnullCSS height override. Ignored for text, whose lines size from size instead.
linesnumber1shape="text" only: number of stacked lines. Past one line, the last one renders shorter.
roundedbooleantrueSet false to square off the corners — handy for a banner image that bleeds to the edge.
ariaLabelstring | nullnullDecorative (aria-hidden) by default, since a page can carry dozens of these while loading. Set on the one instance that stands for the whole loading area — it then becomes an indeterminate role="progressbar" with that name, as gog-spinner does (role="status" before 21.19.0).

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 skeleton 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-skeleton-base / -shinePlaceholder base colour and shimmer. Since 21.15.0 the base is translucent ink — color-mix(in srgb, var(--gog-text-color) 12%, transparent) — rather than a fixed colour, so a bone stands off whatever it sits on by the same step: a filled card’s tint as much as the page. The fixed colour vanished on a filled surface.
--gog-skeleton-radius / -line-radiusCorner radius, block and line shapes.
--gog-skeleton-pulse-duration / -wave-durationLoading animation timing.