Skeleton
A decorative shimmer placeholder that preserves the expected text, avatar, or block layout while content loads.
Implementation previewEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Example source
packages/design-system/src/components/primitives/Skeleton/Skeleton.stories.tsxExport PlaygroundImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A decorative shimmer placeholder that preserves the expected text, avatar, or block layout while content loads.
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { Skeleton } from '@cloakedinc/design-system';SkeletonSkeletonProps
packages/design-system/src/components/primitives/Skeleton/Skeleton.tsx:30
| Prop | Type | Presence | Notes |
|---|---|---|---|
variant | SkeletonVariant | undefined | Optional | Shape preset: corner radius for all three, plus a 16px height for `text`. Defaults to `rectangle`.Source default: 'rectangle' |
width | string | number | undefined | Optional | Width as a number (px) or any CSS length. |
height | string | number | undefined | Optional | Height as a number (px) or any CSS length. |
borderRadius | string | number | undefined | Optional | Corner radius override (number = px); otherwise the variant default applies. |
className | string | undefined | Optional | |
style | React.CSSProperties | undefined | Optional | |
testId | string | undefined | Optional | Selector on the placeholder — it is `aria-hidden`, so there is no role or name to query by. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
A shimmer placeholder that stands in for content while it loads, sized to the shape it replaces.
When to use
Reach for Skeleton to hold the layout in place while data loads, so the screen doesn't jump when
content arrives. It is decorative — aria-hidden and reduced-motion aware — so it never announces a
busy state to assistive tech. Size each placeholder to the real element it stands in for.
- Content finished loading but there's genuinely nothing to show? Use
EmptyState. - Need a small, announced, indeterminate busy indicator (not a layout stand-in)? Use
Spinner, orProgressfor a determinate bar.
Pick variant by the shape you're standing in for:
Usage by variant
| Choice | Use when | Avoid when |
|---|---|---|
text | A line of copy — headings, labels, body runs. Set width to the expected text length. | |
circle | A round element — avatars, icon bubbles. Match width and height. | |
rectangle | A block — cards, images, thumbnails, buttons. The default. |
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- placeholder
- Label
- Placeholder
- Description
- Owns the requested dimensions, shape, and loading shimmer.
- Id
- base
- Label
- Base layer
- Description
- Provides the resting loading surface.
- Id
- highlight
- Label
- Highlight layer
- Description
- Moves across the base to communicate ongoing loading.
Allowed Design Choices
- Variants
- Text
- Label
- Text
- Circle
- Label
- Circle
- Rectangle
- Label
- Rectangle
- Sizes
Variants
- Id
- text
- Label
- Text
- Description
- A 16-unit line placeholder with a compact radius.
- Platforms
- ios
- android
- web
- Id
- circle
- Label
- Circle
- Description
- A fully round placeholder for an avatar or circular icon.
- Platforms
- ios
- android
- web
- Id
- rectangle
- Label
- Rectangle
- Description
- A rounded block placeholder for cards, media, or larger content.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- text-height
- Label
- Text placeholder height
- Kind
- exact
- Token
- --cds-size-16
- Value
- 16
- Unit
- px
- Applies To
- placeholder
- text
- Id
- text-radius
- Label
- Text placeholder radius
- Kind
- exact
- Token
- --cds-radius-xxs
- Value
- 4
- Unit
- px
- Applies To
- placeholder
- text
- Id
- rectangle-radius
- Label
- Rectangle placeholder radius
- Kind
- exact
- Token
- --cds-radius-xs
- Value
- 8
- Unit
- px
- Applies To
- placeholder
- rectangle
Layout
- Alignment
- The placeholder occupies the exact box requested by its parent.
- Flow
- It is a block-shaped decorative replacement for one expected content region.
- Notes
- Set width and height to match the content being reserved; circle placeholders need equal dimensions.
Typography And Color
- Typography
- Label
- Text-line reference
- Description
- The default text placeholder height aligns with the body text size.
- Token
- --cds-type-body-size
- Colors
- Label
- Base
- Description
- Uses the theme-aware skeleton base role.
- Token
- --cds-skeleton-base
- Label
- Highlight
- Description
- Uses the theme-aware skeleton highlight role.
- Token
- --cds-skeleton-highlight
States
- Id
- loading
- Label
- Loading
- Description
- Shows the moving shimmer between base and highlight colors.
- Id
- reduced-motion
- Label
- Reduced motion
- Description
- Shows the same placeholder without shimmer animation.
- Id
- custom-geometry
- Label
- Custom geometry
- Description
- Uses caller-provided dimensions or radius while retaining the selected shape semantics.
Behavior
- Label
- Layout preservation
- Description
- Reserve the approximate geometry of the content that will replace the placeholder.
- Label
- Decoration only
- Description
- Do not use Skeleton as a determinate progress indicator or status message.
Accessibility
- Label
- Hidden placeholder
- Description
- Hide the decorative shape from assistive technology.
- Label
- Busy region
- Description
- When loading must be announced, mark the containing region busy or provide separate status copy.
Content Adaptation
- Label
- Shape matching
- Description
- Use text for a text run, circle for a round identity or icon, and rectangle for a larger block.
- Label
- Unknown content
- Description
- Avoid over-specific placeholder layouts when the eventual content shape is not known.
Motion Haptics
- Motion
- Label
- Shimmer
- Description
- Move the highlight across the base while loading and stop it for reduced motion.
- Haptics
- Label
- No feedback
- Description
- Skeleton is non-interactive and does not request haptic feedback.