Skip to content
Kimenpre-v1documentation home
Color scheme

ki-skeleton

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.

Theme for this example
Color scheme for this example
<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

AttributePropertyTypeDefaultDescription
animatedanimatedbooleantrueSweep a highlight while the user permits motion. Set false to use a static placeholder. Shimmer also stops under reduced motion and forced colours.
block-sizeblockSizestring | 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-sizeinlineSizestring | undefined–CSS length for the inline axis. Use it to match a fixed content width. Text and rectangles otherwise fill available inline space.
lineslinesnumber1Number of text lines. Use a whole number from 1 to 20 for the expected paragraph length. Extra lines are ignored for circles and rectangles.
shapeshape"circle" | "rect" | "text"'text'Match the placeholder to the expected text, avatar, or rectangular content.
sizesizestring | undefined–CSS length shared by both axes. Use it for circles or square blocks. An axis-specific override takes precedence.

CSS parts

PartDescription
shapeEach 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.

TokenDescription
--ki-skeleton-backdrop-filterComplete backdrop filter behind a loading shape. Defaults to none.
--ki-skeleton-bgBase fill of the decorative loading shapes.
--ki-skeleton-bg-imageOptional image layered over the static fill. Defaults to none.
--ki-skeleton-circle-radiusProportional corner radius of the circular shape.
--ki-skeleton-circle-sizeDefault diameter of the circle.
--ki-skeleton-highlightPeak colour of the animated loading highlight.
--ki-skeleton-last-line-scaleFraction of the usual line width occupied by the final line in multiline text.
--ki-skeleton-line-gapBlock-axis space between text lines.
--ki-skeleton-line-sizeDefault height of each text line.
--ki-skeleton-radiusCorner radius of text lines and rectangles.
--ki-skeleton-rect-sizeDefault block size of the rectangle.
--ki-skeleton-shimmer-durationDuration of a shimmer sweep.
--ki-skeleton-shimmer-easingEasing of the shimmer sweep.
--ki-skeleton-shimmer-imageImage of the moving highlight. Use currentColor to inherit the highlight colour.
--ki-typography-family-bodysemantic font family for typography family body.

Workshop

Open ki-skeleton in Storybook