Skip to content

Skeleton

Grey shapes the size of what they stand in for, one sheen sweeping across all of them in step (or a staggered pulse), shown only after a short delay, then a crossfade into the content.

oxyn add skeleton
MCP
Thinking… reading 14 files
Dioxus
rsx! {
    Skeleton {
        lines: 3,
        avatar: true,
        shape: "message",
        loading: loading(),
        Message { message }
    }
}

Rendered from Rust at build time · goes live when visible

When to use

  • Skeletons hold the place of content the agent is about to produce or fetch: the reply before the first token, a source card while its page loads, a generated table while rows stream, a chart while the query runs, a code block while a file is read, a whole "generating this UI" surface in an app builder.
  • The user wants to see what kind of thing is coming and where, so their eye is already in the right place when it arrives, and they want no jump when it does.
  • A skeleton that does not match the shape it is replaced by is worse than none: it moves everything when the real content lands.
  • Research note 02 found no library shipping a skeleton-per-generative-block system with multiple sweep styles; that is the gap this spec fills.

When not to use

  • Fourteen text-glyph loaders (braille, sand, blocks, scanner…) that settle into a check, a warning or a cross when the agent finishes, waits or fails: use Glyph loader instead.
  • A dot and a label for any of the 13 agent states, as a pill, inline or a dot alone: use Status indicator instead.
  • A small turning arc for work that runs right now, plus dots, ray and orbit styles: use Spinner instead.

Installation

Skeleton is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.

Terminal
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add skeleton
Rust
use crate::oxyn::{Skeleton, ShimmerLabel, PRIMITIVES_CSS};

Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{Skeleton, ShimmerLabel, PRIMITIVES_CSS};

Usage

Dioxus · rust
rsx! {
    Skeleton {
        lines: 3,
        avatar: true,
        shape: "message",
        loading: loading(),
        Message { message }
    }
}

Examples

Message

A chat message.

Thinking… reading 14 files
Code
rsx! {
    Skeleton {
        lines: 3,
        avatar: true,
        shape: "message",
        loading: loading(),
        Message { message }
    }
}

Tool rows

Tool calls in a run.

Code
rsx! {
    Skeleton {
        lines: 4,
        avatar: true,
        shape: "tool-row",
        loading: loading(),
        Message { message }
    }
}

Wave

A staggered pulse.

Thinking… reading 14 files
Code
rsx! {
    Skeleton {
        lines: 5,
        avatar: true,
        sweep: "wave",
        loading: loading(),
        Message { message }
    }
}

Loaded

Crossfaded into the content.

MCMaya Chen· 2 min ago

Both tabs call refresh() with the same token; the second one gets 401. A single-flight lock fixes it.

Code
rsx! {
    Skeleton {
        lines: 3,
        avatar: true,
        shape: "message",
        loading: loading(),
        Message { message }
    }
}

API reference

Skeleton

PropTypeDefaultDescription
linesusize3Text lines (1–6).
avatarboolDefault::default()Round avatar placeholder.
shapeString"text"Shape preset.
sweepString"shimmer"`shimmer` · `pulse` · `wave` · `none`.
speedf321.6Sweep period s.
anglef32100.0Sweep angle deg.
loadingbooltrueStill loading.
delayu32150Reveal delay ms.
labelString"Loading content"Status label.
widthf32320.0Width px.
childrenElementDefault::default()Content shown once loaded.

ShimmerLabel

PropTypeDefaultDescription
textrequiredString—Text.
durationf322.0Period s.

Read from the Rust signature and doc comments.

Accessibility

  • role=status with aria-busy and a label; the shapes are aria-hidden.
  • Reduced motion stops the sheen and pulse.
From the spec

research note 11). The container gets aria-busy="true" while Showing / Partial / Stalled and a visually hidden label ("Loading results", "Generating reply").

  • Progress. Skeletons are indeterminate by nature; when a table or list knows its expected count, the container's aria-valuetext says "Loaded 3 of 12 rows".
  • Live region: the skeleton itself announces nothing; family B announces the run, and the host announces completion only if the user requested it ("Results loaded", "Table ready, 12 rows"). Errors are assertive ("Couldn't load results. Retry available").
  • Focus. Nothing focusable inside a skeleton; focus waits on the host; when content swaps in, focus is not moved.
  • Flashing. Sweep period 2 s; pulse 2 s; no skeleton flashes; luminance difference of sweep vs base ≤ 12 % lightness.
  • Contrast. Skeleton shapes are decorative; the "Still loading…" caption and error text meet 4.5:1.
  • Reduced motion: §5 last row.

Motion & interaction

  • Enter. After show_delay, the skeleton fades in (180 ms) at its final footprint. No grow-in; a skeleton that animates its size defeats its purpose.
  • Shimmer (shared sweep). One sweep band (105°, 2 s linear) travels across all skeleton blocks in the viewport together, pinned to the viewport rather than to each block, so a page of skeletons moves 105° sweep matches the Claude desktop skeleton sweep, research note 08).
  • Pulse. All bars breathe opacity 0.45 ↔ 1 on a 2 s ease.in-out loop, in phase.
  • Wave. Bars breathe in sequence, 150 ms stagger per bar in reading order (the staggered generating skeleton in Zed's agent panel, research note 08, uses 4 bars with a 0.15 stagger on a 2 s loop; our values are our own).
  • Partial fill. As real parts arrive (table header, rows, chart axes, first code lines), each replaces its skeleton part with a 120 ms crossfade in place; remaining skeleton parts keep sweeping. Rows arriving faster than 30 ms apart batch into one crossfade.
  • Swap-in without layout jump. Content is laid out invisibly in the same frame; the skeleton crossfades out (180 ms) while content crossfades in; if the measured height differs, the container eases from predicted to actual height (200 ms, spring.snap) with the top edge fixed, so text above never moves and content below shifts once, smoothly. In a chat transcript pinned to the bottom, the scroll anchor compensates so the viewport does not jump.
  • Streaming text. The message skeleton is replaced by the streaming text at the first token (subject to min_display); remaining skeleton lines collapse as text overtakes them, never below the text.
  • Stall. Sweep slows to half speed (2 s ramp) and a muted "Still loading…" caption fades in after the status strip's soft threshold (5 s).
  • Error. The skeleton crossfades into an error block of the same footprint, then height settles; one 4 px shake on the Retry button only (not the block).
Timing
TransitionDurationDelay / staggerEasing / springNotes
Show delay—150 ms—proposed
Skeleton enter (fade)180 ms0ease.outno size animation
Shimmer sweep (loop.sweep)2.0 s per pass—linear105° band, ~30 % of viewport width; 30 fps
Pulse (loop.pulse)2.0 s—ease.in-outopacity 0.45 ↔ 1
Wave2.0 s loop150 ms per bar, cap 8 bars then repeatsease.in-out
Partial part crossfade120 msbatch window 30 msease.out
Min display300 ms total incl. exitcontent may start at +120 ms—decision, proposed
Swap crossfade (out / in)180 ms / 180 mssimultaneousease.in / ease.out
Height settle200 ms0spring.snaptop edge fixed
Stall: slow-down / caption2 s ramp / 160 ms fadecaption after 5 slinear / ease.outthresholds: status strip
Cancel160 ms0ease.in
Reduced motionstatic skeleton tone (no sweep, no pulse, no wave); swap = 80 ms opacity crossfade; height change instant (one jump, no animation); caption still appears on stall——

Responsive behaviour

  • Bars are percentages of the slot width, so it scales with its container.
Edge cases (spec)
  • Unknown content size. Use the block's default shape (message 3 lines, table 5 rows, code 8 lines); the height settle on swap handles the difference once.
  • Predicted much larger than actual (5-row skeleton, 1-row result). Height settles in 200 ms; in a bottom-pinned transcript the scroll anchor keeps the composer and latest message still.
  • Very fast content (< 150 ms). No skeleton.
  • Content between 150 ms and 300 ms. Skeleton shown; content starts fading in at +120 ms after the skeleton's first frame; total skeleton visibility 300 ms including its fade.
  • Very slow (minutes). Sweep continues; Stalled caption; offscreen skeletons stop ticking.
  • Many skeletons (dashboards of 30 cards). One shared sweep for all; per-block pulses are phase-locked to the shared clock; container-loaders.md §4.4 caps apply.
  • Streaming tables. Header first (real), rows replace skeleton rows; when actual rows exceed the skeleton rows, new rows append without skeletons; when fewer, leftover skeleton rows collapse at the end.
  • Charts with unknown type. Bars placeholder; switching to the real type is a crossfade, never a morph between unrelated shapes.
  • Code language unknown. No chip; gutter still shown.
  • RTL. Bars align to the inline-start (right); sweep travels right → left; table numeric columns stay aligned as the real content will be; code blocks stay LTR.
  • Tiny sizes (rows < 20 px). static or pulse only; no sweep band narrower than 24 px.
  • Dark / light themes. Skeleton tone = surface ± 6 % lightness; sweep highlight = surface ± 12 % (proposed); both from tokens.
  • Touch / scroll. Skeletons never intercept input; scrolling a skeleton list does not restart the sweep (it is pinned to the viewport).
  • Virtualised lists. Recycled rows take the new item's skeleton seed immediately.
  • Partial errors (some cards fail). Each card swaps to its own error block; the rest keep loading.

Notes for AI

  • Import Skeleton, ShimmerLabel from oxyn_dioxus and include PRIMITIVES_CSS plus the token stylesheet once.
  • A GPUI version exists: SkeletonEl in oxyn_gpui.
  • Props to set first: text.
  • Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.

Guides

Oxyn · 74 free components · 264 Pro components · 96 screens · 20 blocks · Dioxus and GPUI