Feedback

Stable - @kikita-labs/ui v1.6.1

Skeleton

Directive that applies a non-semantic placeholder treatment to an existing element while known content is loading.

Import

Import the public directive from the published package entrypoint.

skeleton.ts
import { KuiSkeletonDirective } from '@kikita-labs/ui';

Usage

Open in Playground

Apply kuiSkeleton to placeholder elements inside a region marked aria-busy. Skeleton hosts are automatically aria-hidden.

<article kuiCard class="skeleton-composition-example" aria-busy="true">
  <div class="skeleton-composition-example__row">
    <span kuiSkeleton shape="circle" style="inline-size: 40px"></span>
    <div class="skeleton-composition-example__stack">
      <span kuiSkeleton shape="heading" style="inline-size: 45%"></span>
      <span kuiSkeleton shape="text" style="inline-size: 70%"></span>
    </div>
  </div>

  <div class="skeleton-composition-example__stack">
    <span kuiSkeleton shape="text" style="inline-size: 100%"></span>
    <span kuiSkeleton shape="text" style="inline-size: 88%"></span>
    <span kuiSkeleton shape="text" style="inline-size: 64%"></span>
  </div>

  <span kuiSkeleton shape="button" style="inline-size: 100%"></span>
</article>

Shapes

shape maps to Kikita UI skeleton geometry tokens for common placeholder layouts.

text
heading
rect
circle
square
button
badge
<div class="skeleton-shapes-example">
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="text" style="inline-size: 140px"></span>
    <code>text</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="heading" style="inline-size: 180px"></span>
    <code>heading</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="rect" style="inline-size: 140px; block-size: 64px"></span>
    <code>rect</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="circle" style="inline-size: 40px"></span>
    <code>circle</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="square" style="inline-size: 40px"></span>
    <code>square</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="button" style="inline-size: 96px"></span>
    <code>button</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="badge" style="inline-size: 64px"></span>
    <code>badge</code>
  </div>
</div>

Animation

animation controls the placeholder motion. Defaults to shimmer; use pulse or none for quieter surfaces.

shimmer (default)
pulse
none
<div class="skeleton-animation-example">
  <div class="skeleton-animation-example__stack">
    <span kuiSkeleton shape="heading" style="inline-size: 60%"></span>
    <span kuiSkeleton shape="text" style="inline-size: 100%"></span>
    <span kuiSkeleton shape="text" style="inline-size: 80%"></span>
    <code>shimmer (default)</code>
  </div>
  <div class="skeleton-animation-example__stack">
    <span kuiSkeleton shape="heading" animation="pulse" style="inline-size: 60%"></span>
    <span kuiSkeleton shape="text" animation="pulse" style="inline-size: 100%"></span>
    <span kuiSkeleton shape="text" animation="pulse" style="inline-size: 80%"></span>
    <code>pulse</code>
  </div>
  <div class="skeleton-animation-example__stack">
    <span kuiSkeleton shape="heading" animation="none" style="inline-size: 60%"></span>
    <span kuiSkeleton shape="text" animation="none" style="inline-size: 100%"></span>
    <span kuiSkeleton shape="text" animation="none" style="inline-size: 80%"></span>
    <code>none</code>
  </div>
</div>

Composition

Combine skeleton shapes to mirror the loaded layout. Put aria-busy on the parent region, not on each skeleton block.

<article kuiCard class="skeleton-composition-example" aria-busy="true">
  <div class="skeleton-composition-example__row">
    <span kuiSkeleton shape="circle" style="inline-size: 40px"></span>
    <div class="skeleton-composition-example__stack">
      <span kuiSkeleton shape="heading" style="inline-size: 45%"></span>
      <span kuiSkeleton shape="text" style="inline-size: 70%"></span>
    </div>
  </div>

  <div class="skeleton-composition-example__stack">
    <span kuiSkeleton shape="text" style="inline-size: 100%"></span>
    <span kuiSkeleton shape="text" style="inline-size: 88%"></span>
    <span kuiSkeleton shape="text" style="inline-size: 64%"></span>
  </div>

  <span kuiSkeleton shape="button" style="inline-size: 100%"></span>
</article>

API

Inputs verified against @kikita-labs/ui v1.6.1 public typings.

NameTypeDefaultDescription
shape'text' | 'heading' | 'rect' | 'circle' | 'square' | 'button' | 'badge''rect'Placeholder shape mapped to Kikita UI skeleton geometry tokens.
animation'shimmer' | 'pulse' | 'none''shimmer'Placeholder animation mode. Automatically disabled when the user prefers reduced motion, regardless of this value.

Accessibility

Skeleton is decorative placeholder chrome, not an announced loading status.

  • Skeleton hosts are automatically aria-hidden="true" and must not expose text to assistive technology.
  • Put aria-busy="true" on the loading region, not on every skeleton block.
  • Do not make skeleton hosts focusable or interactive.
  • Use kuiLoader instead when the UI needs an announced loading status.
  • Kikita disables skeleton animation under prefers-reduced-motion regardless of the configured animation value.