Skeleton
Decorative loading placeholders with CSS-native dimensions, three geometries, calm motion and complete headless ownership.
GET STARTED
Import
Import the canonical standalone component from its granular entry point.
Basic text placeholders
The rounded default fills its container. Width and height accept CSS length strings instead of framework-specific size shortcuts.
Shapes and dimensions
Circle uses one size value; rectangle and rounded variants use independent dimensions. borderRadius can override any chosen shape.
Pulse, wave and none
Pulse is the calm default, wave communicates active fetching and none creates a completely static placeholder.
Pulse
Wave
None
Content-aware composition
Match the final layout to avoid content shift. The surrounding region—not each decorative bar—owns aria-busy and its stable name.
Static placeholders
Use animation="none" in dense views, snapshots or products where motion would distract. Dimensions and theme surface remain unchanged.
Unstyled and typed slots
Structural clipping and explicit dimensions remain while consumer classes own the root and effect.
Usage boundaries
Skeleton
Represents visual geometry while content is unavailable.
Region
Owns aria-busy, a stable accessible name and replacement timing.
LoadingOverlay
Blocks interaction when the entire surface must wait.
ACCESSIBILITY
Silent placeholders
Skeletons never compete with the content they temporarily represent.
Decorative semantics
Every skeleton is aria-hidden=true and has no role. Screen readers do not announce every visual line or card shape.
Busy regions
Place aria-busy=true on the smallest meaningful region being refreshed and preserve its accessible name across loading and loaded states.
Stable announcements
Do not add a live region to each skeleton. If status narration is necessary, provide one concise status outside the decorative placeholders.
Reduced motion
Both pulse and wave animations stop automatically when prefers-reduced-motion requests reduced movement.
SSR and hydration
Rendering is declarative and browser-global free. Explicit dimensions produce the same server and client geometry.
PUBLIC API
Skeleton contracts
A deliberately small API keeps generated loading layouts predictable.
Inputs
| Input | Type | Default | Purpose |
|---|---|---|---|
| shape | 'rectangle' | 'rounded' | 'circle' | 'rounded' | Selects geometry; circle resolves both dimensions from size. |
| animation | 'pulse' | 'wave' | 'none' | 'pulse' | Selects the visual loading effect. |
| width | string | '100%' | CSS inline size for rectangle and rounded shapes. |
| height | string | '1rem' | CSS block size for rectangle and rounded shapes. |
| size | string | '2.5rem' | CSS width and height used by circle shape. |
| borderRadius | string | null | null | Inline radius override applied after shape styles. |
| unstyled | boolean | false | Removes all NeuralNg visual classes. |
| skeletonClass | string | '' | Additive consumer classes on the root. |
| classes | NeuralSkeletonClasses | {} | Typed root and effect class slots. |
Typed class slots
rootSized decorative placeholder and clipping surface.
effectAnimated wave layer inside the root.
Public types
NeuralSkeletonShape'rectangle' | 'rounded' | 'circle'
NeuralSkeletonAnimation'pulse' | 'wave' | 'none'
NeuralSkeletonClasses{ root?: string; effect?: string }
Legacy alias
SkeletonComponent remains a deprecated compatibility alias. New code and AI-generated examples use NeuralSkeleton.
DESIGN TOKENS
Skeleton tokens
Themes change the placeholder surface and motion without changing component markup.
Surface and shape
--neural-skeleton-backgroundComponent background surface.
--neural-skeleton-rectangle-radiusRectangle corner radius.
--neural-skeleton-rounded-radiusRounded corner radius.
Pulse
--neural-skeleton-pulse-durationPulse animation duration.
--neural-skeleton-pulse-easingPulse animation easing curve.
--neural-skeleton-pulse-min-opacityPulse min opacity.
--neural-skeleton-pulse-max-opacityPulse max opacity.
Wave
--neural-skeleton-wave-widthWave inline size.
--neural-skeleton-wave-backgroundWave background surface.
--neural-skeleton-wave-durationWave animation duration.
--neural-skeleton-wave-easingWave animation easing curve.