Text shimmer
A label with light passing over it while the agent works: a sweep, a calm band, a pulse or an ASCII scan; it stops when the run ends and dims when it stalls.
oxyn add text-shimmerThinking through the auth flow
Dioxus
rsx! {
TextShimmer {
text: "Thinking through the auth flow",
state: agent.state() // stops on done, dims when stalled,
now: clock.now(),
size: 18.0,
}
}Rendered from Rust at build time · goes live when visible
When to use
- A band of light crossing a status word ("Thinking", "Reading auth.rs") is the most common way agent apps say *the model is alive and this text is live, not a finished label*.
- Every app we studied ships one, each with different maths: Codex's cosine band (1 s sweep every 4 s after 600 ms, brightness only), Warp's 3 s cosine with radius 6 glyphs, OpenCode's asymmetric comet (head 4, tail 18, 1.2 s, coast easing), Claude Code's hard ±1-column glimmer at 50 or 200 ms/column, Cline's 5 s Background-position gradient, MonoCode / AI Elements' 2 s gradient; A 1.8 s bell band [note 12], Kits ship one shimmer each (note 02).
- We ship one primitive with named knobs and make each look a preset — and we add what none of them document: a contrast floor, a graceful stop, and per-theme colour rules.
When not to use
- The verb that says what the agent is doing, rotating through a verb pack while it works and settling into the past tense when it finishes: use Verb cycler instead.
- An agent asks before it acts: use Approval Card instead.
- Several open requests in one card: use Approval pager instead.
Installation
Text shimmer 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 text-shimmerRust
use crate::oxyn::{TextShimmer, STATUS_TEXT_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{TextShimmer, STATUS_TEXT_CSS};
Usage
Dioxus · rust
rsx! {
TextShimmer {
text: "Thinking through the auth flow",
state: agent.state() // stops on done, dims when stalled,
now: clock.now(),
size: 18.0,
}
}Examples
Sweep
A bright band sweeps across.
Thinking through the auth flow
Code
rsx! {
TextShimmer {
text: "Thinking through the auth flow",
state: agent.state() // stops on done, dims when stalled,
now: clock.now(),
size: 18.0,
}
}Calm
A slow, wide band.
Thinking through the auth flow
Code
rsx! {
TextShimmer {
text: "Thinking through the auth flow",
state: agent.state() // stops on done, dims when stalled,
now: clock.now(),
variant: "calm",
size: 18.0,
}
}Pulse
The whole label breathes.
Thinking through the auth flow
Code
rsx! {
TextShimmer {
text: "Thinking through the auth flow",
state: agent.state() // stops on done, dims when stalled,
now: clock.now(),
variant: "pulse",
size: 18.0,
}
}Ascii
Characters scan through weights.
Thinking through the auth flow
Code
rsx! {
TextShimmer {
text: "Thinking through the auth flow",
state: agent.state() // stops on done, dims when stalled,
now: clock.now(),
variant: "ascii",
size: 18.0,
}
}API reference
TextShimmer
| Prop | Type | Default | Description |
|---|---|---|---|
textrequired | String | — | The text. |
staterequired | AgentState | — | The agent state (drives start, stop, stall). |
nowrequired | ClockMs | — | Shared clock time. |
variant | String | "sweep" | `sweep` · `calm` · `pulse` · `ascii`. |
line_px | Option<f32> | Default::default() | Measured line width in px; estimated from the text when absent. |
size | f32 | 13.0 | Font size in px. |
reduced | bool | Default::default() | Reduced motion: plain text at full fg. |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| — | Not focusable |
Accessibility
- The shimmer is purely visual; the text node is real text and is the accessible name.
- Nothing is announced by the shimmer; reduced draws plain text at full colour.
From the spec
- The shimmer is purely visual; the text node is real text and the accessible name is the text.
- Host gets
aria-busy="true"while the shimmer is in any active state; cleared onFadingend. - Nothing is announced by the shimmer; announcements belong to the host's live region with the family throttling (status-text.md §11).
- Contrast floor (§3) guarantees ≥ 4.5:1 (3:1 for large text) on every frame; high-contrast themes disable the effect.
- Reduced motion:
Staticat full fg. Flashing: ≤ 1 luminance cycle per second by schema. - Focus ring and selection colours are never altered by the shimmer.
Motion & interaction
- Start. New text arrives at base colour; nothing moves for 600 ms; the first sweep eases in with
ease.coast. A turn that ends inside 600 ms never shimmers. - Text change mid-sweep. The band's amplitude drops to 0 in 100 ms while the verb cycler swaps the text; the clock restarts at
Delay(Codex resets the shimmer clock per header, note 08). Band and swap never overlap. - Graceful stop (done, waiting, error). If the band centre is ≥ 70 % across, it finishes the sweep (≤ 400 ms worst case); otherwise its amplitude fades to 0 over 200 ms while it keeps moving. Base then brightens to full fg over 200 ms. It never snaps off (OpenCode's inactive/active/fading machine, MIT, solves the same problem).
- Stall. At
stall_softthe sweep slows from 1× to 0.5× over 2 s; atstall_hardit freezes and base ramps towardtone.warning(tone ramp owned by status-text). First new event: 200 ms back to normal speed. - Hover. No change by default (status text is peripheral);
pointer-follow(Pro) moves the band to the pointer and returns to auto-sweep 400 ms after the pointer leaves. - Selection. When the user selects the text, the shimmer pauses and selection colours win.
- Off-screen / unfocused. Paused at the current phase; resumes there.
Timing
| Transition | Duration | Delay | Easing / spring | Stagger | Frame rate |
|---|---|---|---|---|---|
| First sweep after text set | 1400 ms (≤ 200 px) / 140 px/s | 600 ms | ease.coast | — | 30 Hz |
| Rest between sweeps | 800 ms | — | — | — | 1 Hz (idle) |
calm cadence | 1000 ms sweep, 3000 ms rest | 600 ms | cosine band, linear travel | — | 30 Hz |
| Band drop on text change | 100 ms | 0 | ease.in | — | 30 Hz |
| Graceful stop (amplitude → 0) | 200 ms | 0 | ease.out | — | 30 Hz |
| Base → fg after stop | 200 ms | after band gone | ease.out | — | 30 Hz |
| Stall slow-down | 2000 ms to 0.5× | stall_soft | linear | — | 30 Hz |
| Recover from stall | 200 ms | 0 | ease.out | — | 30 Hz |
pulse breath | 2000 ms loop, amplitude 0.6 | 600 ms | sine | — | 30 Hz |
wave (Pro) per-glyph y bob | 1 px, 1200 ms | — | sine | 45 ms/glyph | 60 Hz |
| Terminal tiers | sweep 2000 ms | 600 ms | linear | — | 30 Hz (frame-quantised) |
| Reduced motion | no band, no pulse: text static at full fg (not base — dimmed static text looks disabled); stall shown as instant tone change + text | — | — | — | 0 Hz |
Responsive behaviour
- line_px tells it the measured width; otherwise it estimates from the text.
Edge cases (spec)
- Very short text (1–3 graphemes, e.g. "…", "Go").
half_widthminimum makes the whole word glow together; below 3 graphemessweepauto-switches topulse(proposed). - Very long text (> 400 px). Speed cap 140 px/s; the band stays a readable width; a model-written header longer than 60 chars is middle-truncated by the host before shimmering.
- Wrapped / multi-line text. Status hosts are single-line; if a host wraps (narrow mobile), each line sweeps in order with a 120 ms offset, never simultaneously.
- RTL. Direction = reading direction of the paragraph; mixed-direction runs are sampled by visual x, so the band moves smoothly across the screen even where the logical order jumps.
- CJK / complex scripts. Sampling at each grapheme's centre; full-width glyphs take one colour; conjuncts never split.
- Emoji. Colour emoji get opacity modulation only (0.85 ↔ 1), never a colour mix.
- Tiny sizes (16–20 px rows, 11–12 px type).
calmcadence and 1.0 em minimum half-width; on a 20 px row the shimmer is the only motion (loader becomes static). - Screen width / zoom. Half-width and speed are in em/px of the text, re-measured on zoom; no restart of the clock on re-measure.
- 0 s / very fast turns. Never visible (600 ms delay). Very slow turns. After 5 min, rest grows to 2.4 s (proposed) so the line calms down.
- Many shimmers on screen. All phase-locked to the shared clock; capped at 8 animated (status-text §10); extra ones render
Static. - Selection, copy. Copy gives plain text; shimmer never inserts characters.
- Transparent / image backgrounds. Contrast floor uses the host's declared
bgtoken; on unknown backgrounds (glass),amplitudeis capped at 0.5 and base dim at 20 % (proposed).
Notes for AI
- Import
TextShimmerfromoxyn_dioxusand includeSTATUS_TEXT_CSSplus the token stylesheet once. - A GPUI version exists:
TextShimmerElinoxyn_gpui. - Props to set first:
text,state,now. - It reads a clock (
now) for live timers; pass one clock for the whole page rather than one per component. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.