Pricing

Skeleton handbook

v1.4.0 · @snowui-design-system/components

License: Before first reading component documentation, source code, or npm usage instructions, read the complete LICENSE. One review covers the same task and version. Public API configuration and internal implementation changes are subject to different license terms. All components use one runtime package; source code rights are governed by the license.

Overview

Show placeholder shapes while content loads so users can anticipate the page structure and the layout stays stable.

When to use it

Use Skeleton for loading placeholders. If a component already supports loading / skeleton, set that state and let the component provide its own shape instead of redrawing it on the page.

  • loading=false renders real children; while loading, use variant / width / height or renderHints to define the placeholder.

  • Prefer the host component’s loading placeholder. Standalone skeleton dimensions and radii still use design-system tokens.

Quick start

This example shows the recommended basic composition. See the following sections for more scenarios and composition limits.

<script lang="ts">	import { Skeleton, Frame } from '@snowui-design-system/components';</script> <Frame row enableAutoLayout={false} style="width: min(100%, 20rem); display: flex; align-items: center; gap: var(--gap-3);">	<Skeleton variant="circle" width={48} height={48} />	<Frame column enableAutoLayout={false} style="flex: 1; min-width: 0; gap: var(--gap-2);"><Skeleton variant="line" width="42%" height={14} /><Skeleton variant="line" width="92%" height={12} /><Skeleton variant="line" width="68%" height={12} /></Frame>	<Skeleton variant="rect" width={72} height={32} /></Frame>

API

Keyword Type Default Description
variant SkeletonVariant — The skeleton shape is explicitly specified; the alias will be normalized to line / circle / rect
width string | number — Explicit width; numeric values are converted to rem.
height string | number — The explicit height; the number will be automatically converted to rem
componentClass string — Compatibility input for older callers. Historical defaults apply only without renderHints; new components must not register through this prop.
renderHints FrameRenderHints — Component self-registration protocol supporting variant / width / height / radius / rows.
loading boolean true Whether to show the skeleton; render children when false
responsive ResponsiveConfig — Responsive width and height overrides.
class string "" External class; applied to the layout container for multiple skeletons or the block itself for one skeleton.
style string "" Inline style; applied to the layout container for multiple skeletons or the block itself for one skeleton.
children Snippet — Parameterless real child content rendered when the skeleton is hidden. While active, the component renders the skeleton layout instead.

See the base component documentation for inherited capabilities not redeclared here. This table lists only the named public props declared in this component’s source.

Usage boundaries and details

Layout model

Main layout model: intrinsic atomic layout.

  • As a placeholder primitive, Skeleton takes dimensions first from the component’s renderHints. Explicit variant / width / height override those hints; legacy componentClass mappings are compatibility only. As a child of an external layout, it hugs content or uses the caller’s fixed dimensions.

  • Multiple text lines and overlapping avatar-group placeholders are private Skeleton layouts that mimic the target component. They do not expose a general-purpose region protocol.

  • Skeleton does not output data-auto-layout; Frame's loading protocol is responsible for deciding whether to render Skeleton, and Skeleton itself does not take over the host layout.

Scope of application

  • Render Skeleton explicitly in a test or demo to inspect its defaults.

  • Frame calls it internally as the default placeholder in the loading + skeleton protocol.

  • Use component renderHints to supply final skeleton dimensions and row counts.

2.2 renderHints rules

Field Type Description
variant "line" | "circle" | "rect" Override the default skeleton shape
width string | number Override the default width
height string | number Override the default height
radius string | number Override skeleton radius; numbers become rem using a nominal 16px base.
rows number Values above 1 expand into multiple line placeholders; the last line is 30% of the container width.

Without radius, a non-circular Skeleton uses var(--radius-3, 0.75rem); circle always uses 50%. Legacy Icon class mappings retain a compatible rect + 50% appearance.

Resolution order

Skeleton resolves its layout in this order:

  1. With renderHints, the component is considered self-registered and the layout uses those hints; explicit variant / width / height override individual fields.

  2. Without hints, explicit variant / width / height render a single skeleton.

  3. Only legacy callers without hints or explicit geometry use the historical componentClass layout.

  4. If nothing matches, fall back to a generic rect skeleton.

4.1 General style

Rule Value
Background color var(--black-10, #0000001a)
Animation snowui-skeleton-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite
Interaction pointer-events: none; user-select: none;
Display display: block

4.2 Layout container style

Rule Value
Layout mode display: flex
Default alignment align-items: center
Default spacing var(--gap-2)
Font size variable --snowui-skeleton-font-size: var(--text-14)
Row height variable --snowui-skeleton-line-height: var(--leading-14)

Supplementary rules:

  • .snowui-skeleton-layout-single will cut back to display: block.

  • .snowui-skeleton-layout-text will change to vertical layout: width: 100%; flex-direction: column; align-items: stretch;

  • .snowui-skeleton-layout-avatar-group Keep gap: 0.

4.3 Shape default value

Shape Default width Default height Default radius
line 6rem 1.25rem var(--radius-3, 0.75rem)
circle 2.5rem 2.5rem 50%
rect 6rem 3rem var(--radius-3, 0.75rem)

Supplementary rules:

  • The default rounded corners of line and rect are unified as 12px.

  • circle always uses border-radius: 50%.

  • line, circle, and rect all use max-width: 100%; max-height: 100% as a fallback.

Text skeleton rules

Any registered component can be expanded into multiple text skeletons with renderHints.rows; Text will automatically calculate the number of lines according to the content.

6.1 Source of the number of lines

  • Text itself will count the number of first-level block-level text paragraph nodes in the skeleton state.

  • The following tags are counted:

    • div

    • p

    • li

    • blockquote

    • h1-h6

  • Direct text at the first level adds one more row.

  • At least one row is rendered.

6.2 Multi-text skeleton layout

Rule Value
Layout direction Stacked vertically
Container width renderHints.width / The width of the first line; 100% when not provided
Earlier row widths 100%
The width of the last line 30%
Single-line height 1.25rem

The rendering rules of the first layer

Skeleton does not recursively inspect the whole component tree; it examines only the first level.

  • When a component itself enters loading + skeleton, render its own Skeleton first.

  • Do not continue to expand subcomponents such as Icon / Text / Avatar inside the component.

  • When Frame enters loading + skeleton:

    • If first-level direct children are self-registered components, render only their corresponding Skeletons.

    • If there are no components at the first level, Frame falls back to a text-shaped Skeleton.

Size rules

  • The number width / height will be converted to rem.

  • Skeleton gives priority to the final geometry provided by the component through renderHints.width / height / radius / rows.

  • When a component provides size hints, its rounded-rectangle Skeleton follows the final component width and height instead of falling back to a generic short width.

  • There is currently no general mechanism to measure actual DOM dimensions.

Usage examples

 <div class="flex flex-col gap-8">    <Skeleton variant="text" width="12rem" />    <Skeleton variant="circular" width={40} height={40} />    <Skeleton variant="rectangular" width="16rem" height="6rem" /></div>  <Frame loading={pageLoading}>    <Button>Submit</Button>    <Text>Loading text</Text></Frame>  <Frame loading skeleton>    <Button variant="filled">        <Icon />        <Text>Search</Text>    </Button></Frame>  <Text loading skeleton class="w-full">    <div>Paragraph one</div>    <div>Paragraph two</div>    <div>Paragraph three</div></Text>  <Frame    loading={pageLoading}    skeleton={false}    whileLoad={{ opacity: 0.6, scale: 0.98 }}>    <Button>Submit</Button></Frame>

Skeleton style overlay

Read the complete LICENSE first; one review covers the same task, version, and scope.

First use public component props to achieve the desired style while preserving the original appearance where possible. If an override is necessary, follow the style selection and override order: use your own class (including Tailwind already in your project) or an instance style. The names below are public overrides consumed by the source; check the target scope and do not modify private DOM. Choose the appropriate SnowUI token category. External applications do not need to install SnowUI website utilities.

Variable Purpose and default reference
--snowui-skeleton-background-override Background (see component source for the default).
--snowui-skeleton-font-size-override font-size (see component source for the default).
--snowui-skeleton-gap-override Layout container gap (default var(--gap-2) = 8px)
--snowui-skeleton-height-override Height (see the component source code for the default value)
--snowui-skeleton-line-height-override line-height (see component source for the default).
--snowui-skeleton-line-radius-override Line rounded corner (default var(--radius-3) = 12px)
--snowui-skeleton-radius-override Border-radius (see the component source code for the default value)
--snowui-skeleton-rect-radius-override Rect rounded corner (default var(--radius-3) = 12px)
--snowui-skeleton-width-override Width (see the component source code for the default value)

Design Guide · Token · Combination Boundary

Skeleton type and status

Required props: no named required props.

Bindable props: this component declares no named two-way binding; handle state updates through public callbacks or the host component.

Inheritance: no interface inheritance.

Shared Frame API · Back to API

The following source type declarations are referenced by public props. Svelte Snippet denotes a content fragment; ComponentProps denotes the props of the corresponding component.

SkeletonVariant

Source: components/src/components/Skeleton.svelte

export type SkeletonVariant =        | "line"        | "circle"        | "rect"        | "text"        | "circular"        | "rectangular";

RenderHints

Source: components/src/logic/frame-types.ts

export interface RenderHints {    variant?: SkeletonRenderVariant;    width?: string | number;    height?: string | number;    radius?: string | number;    rows?: number;}

SkeletonRenderVariant

Source: components/src/logic/frame-types.ts

export type SkeletonRenderVariant = "line" | "circle" | "rect";

ResponsiveConfig

Source: components/src/logic/responsive.svelte.ts

export type ResponsiveConfig = Partial<Record<Breakpoint, ResponsiveRule>>;

Breakpoint

Source: components/src/logic/responsive.svelte.ts

export type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';

ResponsiveRule

Source: components/src/logic/responsive.svelte.ts

export interface ResponsiveRule {    collapsed?: boolean;    expanded?: boolean;    style?: string;    class?: string;    props?: Record<string, any>;}