Skip to content
Back

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-shimmer
MCP
Thinking 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-shimmer
Rust
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

PropTypeDefaultDescription
textrequiredString—The text.
staterequiredAgentState—The agent state (drives start, stop, stall).
nowrequiredClockMs—Shared clock time.
variantString"sweep"`sweep` · `calm` · `pulse` · `ascii`.
line_pxOption<f32>Default::default()Measured line width in px; estimated from the text when absent.
sizef3213.0Font size in px.
reducedboolDefault::default()Reduced motion: plain text at full fg.

Read from the Rust signature and doc comments.

Keyboard interactions

KeyAction
—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 on Fading end.
  • 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: Static at 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_soft the sweep slows from 1× to 0.5× over 2 s; at stall_hard it freezes and base ramps toward tone.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
TransitionDurationDelayEasing / springStaggerFrame rate
First sweep after text set1400 ms (≤ 200 px) / 140 px/s600 msease.coast—30 Hz
Rest between sweeps800 ms———1 Hz (idle)
calm cadence1000 ms sweep, 3000 ms rest600 mscosine band, linear travel—30 Hz
Band drop on text change100 ms0ease.in—30 Hz
Graceful stop (amplitude → 0)200 ms0ease.out—30 Hz
Base → fg after stop200 msafter band goneease.out—30 Hz
Stall slow-down2000 ms to 0.5×stall_softlinear—30 Hz
Recover from stall200 ms0ease.out—30 Hz
pulse breath2000 ms loop, amplitude 0.6600 mssine—30 Hz
wave (Pro) per-glyph y bob1 px, 1200 ms—sine45 ms/glyph60 Hz
Terminal tierssweep 2000 ms600 mslinear—30 Hz (frame-quantised)
Reduced motionno 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_width minimum makes the whole word glow together; below 3 graphemes sweep auto-switches to pulse (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). calm cadence 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 bg token; on unknown backgrounds (glass), amplitude is capped at 0.5 and base dim at 20 % (proposed).

Notes for AI

  • Import TextShimmer from oxyn_dioxus and include STATUS_TEXT_CSS plus the token stylesheet once.
  • A GPUI version exists: TextShimmerEl in oxyn_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.

Guides

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