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 skeletonrsx! {
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.
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add skeletonuse 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
rsx! {
Skeleton {
lines: 3,
avatar: true,
shape: "message",
loading: loading(),
Message { message }
}
}Examples
Message
A chat message.
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.
Code
rsx! {
Skeleton {
lines: 5,
avatar: true,
sweep: "wave",
loading: loading(),
Message { message }
}
}Loaded
Crossfaded into the content.
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
| Prop | Type | Default | Description |
|---|---|---|---|
lines | usize | 3 | Text lines (1–6). |
avatar | bool | Default::default() | Round avatar placeholder. |
shape | String | "text" | Shape preset. |
sweep | String | "shimmer" | `shimmer` · `pulse` · `wave` · `none`. |
speed | f32 | 1.6 | Sweep period s. |
angle | f32 | 100.0 | Sweep angle deg. |
loading | bool | true | Still loading. |
delay | u32 | 150 | Reveal delay ms. |
label | String | "Loading content" | Status label. |
width | f32 | 320.0 | Width px. |
children | Element | Default::default() | Content shown once loaded. |
ShimmerLabel
| Prop | Type | Default | Description |
|---|---|---|---|
textrequired | String | — | Text. |
duration | f32 | 2.0 | Period 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-valuetextsays "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-outloop, 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
| Transition | Duration | Delay / stagger | Easing / spring | Notes |
|---|---|---|---|---|
| Show delay | — | 150 ms | — | proposed |
| Skeleton enter (fade) | 180 ms | 0 | ease.out | no size animation |
Shimmer sweep (loop.sweep) | 2.0 s per pass | — | linear | 105° band, ~30 % of viewport width; 30 fps |
Pulse (loop.pulse) | 2.0 s | — | ease.in-out | opacity 0.45 ↔ 1 |
| Wave | 2.0 s loop | 150 ms per bar, cap 8 bars then repeats | ease.in-out | |
| Partial part crossfade | 120 ms | batch window 30 ms | ease.out | |
| Min display | 300 ms total incl. exit | content may start at +120 ms | — | decision, proposed |
| Swap crossfade (out / in) | 180 ms / 180 ms | simultaneous | ease.in / ease.out | |
| Height settle | 200 ms | 0 | spring.snap | top edge fixed |
| Stall: slow-down / caption | 2 s ramp / 160 ms fade | caption after 5 s | linear / ease.out | thresholds: status strip |
| Cancel | 160 ms | 0 | ease.in | |
| Reduced motion | static 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;
Stalledcaption; 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).
staticorpulseonly; 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,ShimmerLabelfromoxyn_dioxusand includePRIMITIVES_CSSplus the token stylesheet once. - A GPUI version exists:
SkeletonElinoxyn_gpui. - Props to set first:
text. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.