The Skeleton component provides visual placeholders for content that is loading. It preserves layout structure while indicating to users that content is being fetched, improving perceived performance and user experience.

Installation

Install the Skeleton component from the Catalyst component library:

npm install @pmi/catalyst-skeleton

Examples

Basic Usage

Simple skeleton placeholders for text content:

Custom Styling

Override default colors with custom styling using CVA or Tailwind classes:

Text Content

Skeleton wrapped around text content preserves the layout structure:

Component Children

Skeleton can wrap interactive components while preserving their structure:

Component Children with Custom Styling

Apply custom neutral color palette to component skeletons:

Custom Size

Skeleton adapts to any custom dimensions:

Variants

The Skeleton component provides two visual variants for different use cases:

Foreground Variant

Use for text, buttons, and interactive elements:

Background Variant

Use for cards, containers, and background elements:

Light Theme Variants

Foreground and background variants in light theme:

Light Theme with Custom Styling

Custom neutral color palette in light theme:

Dark Theme Variants

Foreground and background variants in dark theme:

Dark Theme with Custom Styling

Custom neutral color palette in dark theme:

Precomposed Card Layout

Complete card component with skeleton states:

Advanced Examples

API Reference

Skeleton Props

The component also accepts all standard HTML span element attributes.

Custom Styling

The product variant supports custom color schemes through CVA (class-variance-authority) or direct Tailwind classes. This is useful for matching specific brand guidelines or design systems.

Creating Custom Variants

import { cva } from 'class-variance-authority';

const customSkeletonVariants = cva('', {
  variants: {
    variant: {
      background: '!bg-neutral-100 dark:!bg-neutral-500',
      foreground: '!bg-neutral-200 dark:!bg-neutral-600',
    },
  },
});

Applying Custom Styles

<Skeleton variant="foreground" className={cn(customSkeletonVariants({ variant: 'foreground' }))}>
  Content
</Skeleton>

The custom styling approach allows you to:

• Override default PMI brand colors with neutral palettes
• Match existing design system colors
• Create variant-specific color schemes
• Maintain consistency across custom components

Accessibility

The Skeleton component implements several accessibility features to ensure a good experience for all users:

ARIA Attributes

• aria-hidden="true": Hides skeleton content from screen readers since it's purely decorative
• tabIndex={-1}: Removes skeleton from keyboard navigation flow
• inert attribute: Prevents all interaction with skeleton content (modern browsers)

Motion Preferences

The pulse animation respects user motion preferences through the motion-safe: modifier. Users who have enabled "Reduce Motion" in their system settings will see static skeletons instead of animated ones.

Loading State Communication

When using the loading prop to toggle between skeleton and real content, ensure you communicate the loading state to screen readers using appropriate ARIA live regions:

<div aria-live="polite" aria-busy={loading}>
  <Skeleton loading={loading}>{content}</Skeleton>
</div>

Visual Accessibility

• Color contrast meets WCAG 2.1 AA standards in both light and dark themes
• Skeleton colors are distinct from actual content colors
• Transparent text overlay prevents partial content visibility during loading

Best Practices

1. Preserve Layout: Use skeletons that match the dimensions of actual content
2. Progressive Disclosure: Show skeletons immediately, don't wait for loading states
3. Consistent Timing: Don't show skeletons for very quick operations (< 300ms)
4. Realistic Shapes: Match skeleton shapes to actual content structure

Design Tokens

The Skeleton component uses the following Catalyst design tokens:

Default Colors

Foreground Variant (for text and interactive elements):

• Light theme: pmi-neutral-100
• Dark theme: pmi-off-black-500

Background Variant (for cards and containers):

• Light theme: pmi-neutral-50
• Dark theme: pmi-off-black-300

Custom Colors (Product Variant)

Foreground Variant:

• Light theme: neutral-200
• Dark theme: neutral-600

Background Variant:

• Light theme: neutral-100
• Dark theme: neutral-500

Text Colors (for surrounding content):

• Primary: pmi-off-black-800
• Secondary: pmi-off-black-400
• Dark mode primary: white
• Dark mode secondary: pmi-neutral-100

Animation

• Pulse animation: motion-safe:animate-pulse
• Respects prefers-reduced-motion media query

Border Radius

• Default: rounded (0.25rem)
• Inherited from children when forceRadius is false

Usage Guidelines

When to Use Skeleton

• Content Loading: Show skeletons while fetching data from APIs
• Progressive Enhancement: Display layout structure before content arrives
• Perceived Performance: Reduce perceived wait time with visual feedback
• Complex Layouts: Preserve page structure during loading states

Foreground vs Background

Use Foreground Variant when wrapping:

• Text content (headings, paragraphs, labels)
• Interactive elements (buttons, links, form controls)
• Icons and badges
• Navigation items

Use Background Variant when wrapping:

• Cards and panels
• Containers and sections
• Image placeholders
• Large content blocks

Animation Guidelines

Use Animated Skeletons for:

• Initial page loads
• Slow network conditions
• Long-running operations

Use Static Skeletons for:

• Background variant containers (prevents nested animations)
• Quick loading states
• Nested skeleton patterns

See Also

• Button - Interactive button component
• Badge - Status and category badges
• Card - Container component for grouped content
• Switch - Toggle switch component
• Checkbox - Checkbox input component