ki-skeleton
@kimen/elements/ki-skeleton- Source
- Agent reference
Match the placeholder to the space the content will use. Text draws one full line by default. Use lines for a paragraph, shape="circle" for an avatar, and shape="rect" for a cover or other block.
<section aria-busy="true" aria-label="Loading project" style="display:grid;gap:var(--ki-space-md);max-inline-size:18rem"><ki-skeleton shape="circle" size="2.5rem"></ki-skeleton><ki-skeleton shape="text" lines="3"></ki-skeleton><ki-skeleton shape="rect" block-size="6rem"></ki-skeleton></section>Reserve the region’s block size at the start of the request. Set aria-busy="true" on the named region and reveal the shapes after about 300 ms. If the request settles earlier, cancel the reveal. Replace the shapes with the result and clear the busy state. The shapes are hidden from assistive technology.
Use animated="false" for static shapes. Reduced motion and forced colours also use static shapes.
API reference
When to use: Reserve the expected layout of a card, list, or assistant reply while it loads. Give the surrounding region an accessible name and set its aria-busy state. Show the skeleton after about 300 ms of waiting.
When not to use: For a standalone loading announcement, progress measurement, or interactive control. Put content and loading feedback in the caller's region.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
animated | animated | boolean | true | Sweep a highlight while the user permits motion. Set false to use a static placeholder. Shimmer also stops under reduced motion and forced colours. |
block-size | blockSize | string | undefined | – | CSS length for the block axis. For text, this is the height of each line. Use it to reserve the height of the content that will replace the shape. |
inline-size | inlineSize | string | undefined | – | CSS length for the inline axis. Use it to match a fixed content width. Text and rectangles otherwise fill available inline space. |
lines | lines | number | 1 | Number of text lines. Use a whole number from 1 to 20 for the expected paragraph length. Extra lines are ignored for circles and rectangles. |
shape | shape | "circle" | "rect" | "text" | 'text' | Match the placeholder to the expected text, avatar, or rectangular content. |
size | size | string | undefined | – | CSS length shared by both axes. Use it for circles or square blocks. An axis-specific override takes precedence. |
CSS parts
| Part | Description |
|---|---|
shape | Each painted text line, circle or rectangle. |
CSS custom properties
The public styling contract of ki-skeleton: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-skeleton-backdrop-filter | Complete backdrop filter behind a loading shape. Defaults to none. |
--ki-skeleton-bg | Base fill of the decorative loading shapes. |
--ki-skeleton-bg-image | Optional image layered over the static fill. Defaults to none. |
--ki-skeleton-circle-radius | Proportional corner radius of the circular shape. |
--ki-skeleton-circle-size | Default diameter of the circle. |
--ki-skeleton-highlight | Peak colour of the animated loading highlight. |
--ki-skeleton-last-line-scale | Fraction of the usual line width occupied by the final line in multiline text. |
--ki-skeleton-line-gap | Block-axis space between text lines. |
--ki-skeleton-line-size | Default height of each text line. |
--ki-skeleton-radius | Corner radius of text lines and rectangles. |
--ki-skeleton-rect-size | Default block size of the rectangle. |
--ki-skeleton-shimmer-duration | Duration of a shimmer sweep. |
--ki-skeleton-shimmer-easing | Easing of the shimmer sweep. |
--ki-skeleton-shimmer-image | Image of the moving highlight. Use currentColor to inherit the highlight colour. |
--ki-typography-family-body | semantic font family for typography family body. |