Skeleton

A placeholder component used to indicate loading content while preserving layout structure. It supports multiple sizes, shimmer animation, shape variants, and composable helpers for common UI patterns.

---

Usage

Basic usage

import { Skeleton } from '@nofinite/nui';

<Skeleton />;

Custom width and height

<Skeleton width={200} height={20} />

Circle skeleton

<Skeleton circle width={48} />

Disable animation

<Skeleton animated={false} />

---

Helper Components

Text

<Skeleton.Text width="60%" />

Paragraph

<Skeleton.Paragraph lines={3} />

Avatar

<Skeleton.Avatar size={40} />

Button

<Skeleton.Button width={120} height={40} />

Card

<Skeleton.Card />

---

Props

Prop	Type	Default	Description
size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Default height size
width	number | string	—	Explicit width override
height	number | string	—	Explicit height override
animated	boolean	true	Enables shimmer animation
circle	boolean	false	Circular skeleton shape
ariaHidden	boolean	true	Hides skeleton from assistive tech
className	string	—	Additional styles
style	CSSProperties	—	Inline style overrides

Extends HTMLSpanElement attributes.

---

Variants

Size variants

<Skeleton size="xs" />
<Skeleton size="sm" />
<Skeleton size="md" />
<Skeleton size="lg" />
<Skeleton size="xl" />

Available variants

• xs
• sm
• md
• lg
• xl

Guidelines

• xs/sm → dense UI or metadata lines
• md → default text placeholders
• lg/xl → headings or large elements

---

States

• Animated shimmer
• Static (animation disabled)
• Circle shape
• Explicit size override
• Dark mode
• Reduced motion (respects OS preference)

---

Accessibility

• Uses role="presentation"
• Hidden from assistive technologies by default (aria-hidden)
• Respects prefers-reduced-motion
• Prevents pointer interaction
• Preserves layout to avoid CLS (Cumulative Layout Shift)

---

Design Tokens

Token	Usage
--nui-bg-subtle	Skeleton base background
--nui-radius-sm	Default radius
--nui-space-*	Layout spacing in helpers
--nui-border-default	Card helper border
--nui-radius-md/lg	Helper shapes

---

Best Practices

Do

• Match skeleton layout with real content
• Disable animation for long-loading screens if performance sensitive
• Use circle skeleton for avatars and icons
• Use paragraph helper for text-heavy layouts
• Combine helpers to mirror complex UI

Don’t

• Use skeleton for extremely short loading durations
• Animate excessively in data-dense views
• Display skeleton after content is partially loaded
• Replace error states with skeleton
• Use mismatched skeleton sizes causing layout shift