Text Reveal
Streamed text arriving: tokens fade in, words un-blur, a typewriter or instant, with a bar, block or underscore caret that leaves when the stream ends.
oxyn add text-revealWhy does login fail when two tabs refresh at once?
Dioxus
rsx! {
TextReveal {
text: answer() // everything received so far, append-only,
now: clock.now(),
ended: stream.is_done(),
}
}Rendered from Rust at build time · goes live when visible
When to use
- While the agent answers, tokens arrive in bursts: nothing for 400 ms, then 300 characters at once, then a trickle.
- The user is *reading as it arrives*.
- Raw appends feel jerky; heavy animation lags behind the model and makes a fast model look slow; half-written markdown flashes raw ` and link: Codex commits whole lines with a two-gear catch-up and a table hold-back; MonoCode repairs unterminated markdown per block (Streamdown + remend); Claude desktop fades graphemes in from a 6 px blur (reverse-engineered, note 08); Streamdown animates per-word spans for 150 ms and removes them when done; LibreChat staggers 25 ms and uses Intl.Segmenter` for CJK; a trailing fade keeps the last 3–5 words lighter [R019]; a word blur-in uses 8 px → 0, y +4 → 0, ~60 ms stagger [R051].
- Smoothers (smooth-stream-text, use-smooth-text) prove that pacing and visual effect must be two separate layers** or they fight (note 02).
When not to use
- A label with light passing over it while the agent works: use Text shimmer instead.
- Send, stop, queue and steer in one control, in twelve styles: use Send control instead.
- An agent asks before it acts: use Approval Card instead.
Installation
Text Reveal 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-revealRust
use crate::oxyn::{TextReveal, STATUS_TEXT_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{TextReveal, STATUS_TEXT_CSS};
Usage
Dioxus · rust
rsx! {
TextReveal {
text: answer() // everything received so far, append-only,
now: clock.now(),
ended: stream.is_done(),
}
}Examples
Fade token
Tokens fade in.
Why does login fail when two tabs refresh at once?
Code
rsx! {
TextReveal {
text: answer() // everything received so far, append-only,
now: clock.now(),
ended: stream.is_done(),
}
}Word blur
Words un-blur.
Why does login fail when two tabs refresh at once?
Code
rsx! {
TextReveal {
text: answer() // everything received so far, append-only,
now: clock.now(),
ended: stream.is_done(),
variant: "word-blur",
}
}Typewriter
Character by character, block caret.
Why does login fail when two tabs refresh at once?
Code
rsx! {
TextReveal {
text: answer() // everything received so far, append-only,
now: clock.now(),
ended: stream.is_done(),
variant: "typewriter",
caret: "block",
}
}Instant
No animation.
Why does login fail when two tabs refresh at once?
Code
rsx! {
TextReveal {
text: answer() // everything received so far, append-only,
now: clock.now(),
ended: stream.is_done(),
variant: "instant",
caret: "underscore",
}
}API reference
TextReveal
| Prop | Type | Default | Description |
|---|---|---|---|
textrequired | String | — | Everything received so far (append-only). |
nowrequired | ClockMs | — | Shared clock time. |
ended | bool | Default::default() | The stream ended normally. |
interrupted | bool | Default::default() | The user stopped the stream. |
stalled | bool | Default::default() | The stream is stalled. |
variant | String | "fade-token" | `fade-token` · `word-blur` · `typewriter` · `line-commit` · `instant`. |
caret | String | "bar" | `bar` · `block` · `underscore`, or empty for no caret. |
reduced | bool | Default::default() | Reduced motion. |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| — | Not focusable |
Accessibility
- Real text nodes; screen readers are never fed tokens (no aria-live on the message).
- The caret and effect spans are aria-hidden; reduced motion keeps the caret static.
From the spec
- Streaming message: real text nodes; container
aria-busy="true"while streaming;aria-liveoff on the message itself — screen readers are never fed tokens. - Announcements (polite, via the family live region): "Response started" (optional), "Response complete", "Interrupted", "Failed". Opt-in
announce = Paragraphs: each *completed* paragraph is announced, throttled to one per 5 s and never mid-sentence (proposed). - Users can read partial content at any time; the caret and effect spans are
aria-hiddenand do not split words for assistive tech (span unwrapping on settle; during streaming the accessible text is the concatenated text). - Contrast: settled text is full fg; transient dim levels (trailing-fade, ink-settle, math raw) respect the contrast floor (≥ 4.5:1 for anything held longer than 300 ms; ≥ 3:1 for carets).
- Reduced motion: §4 last row; caret static; follow scroll instant.
- Blinking: caret blink stops after 5 s idle (WCAG 2.2.2).
- Focus: streaming never steals focus from the composer; "↓ New output" pill is reachable after the message in tab order and via End.
Motion & interaction
- First token. Caret (or the host's "Thinking" line) is replaced by text with the effect; the message container height grows downward only, with the composer never moving (composer.md rule).
- Burst. CatchUp blocks fade in as wholes — the user sees paragraphs land, not a sprint of words.
- End. Draining flush ≤ 300 ms → caret fade 200 ms → animation spans unwrapped (one relayout, invisible because positions are identical) → message actions fade in 120 ms.
- Stop. Everything received appears instantly; no further effects; the status strip drops "Interrupted" into the transcript.
- New output pill. Slides up 8 px + fade (160 ms
ease.out); count rolls withdur.digit.roll. - Retry / regenerate. Old text crossfades to 40 % and collapses when the new stream's first block lands (200 ms), so the user does not read stale text as new.
Responsive behaviour
- Wraps like body text; the caret follows the last line.
Edge cases (spec)
- RTL. Units and stagger follow logical order, so the reveal visually moves right → left;
slide-inmirrors; the caret sits at the logical end (visual left). Mixed-direction lines are shaped once per frame on the tail only. - CJK / Thai. No word spaces: word effects use per-grapheme units with the same caps; line-breaking follows the platform's rules; the pacer's
40 graphemes/sminimum becomes 20 (denser script — proposed). - Emoji / ZWJ sequences. Revealed only when the full cluster has arrived (a half sequence is never shown as two emoji).
- Very long words / URLs. Break anywhere after 40 characters in prose; never inside inline code.
- Screen width. Narrow (< 360 px) disables blur effects (cost and legibility) →
fade-token. - 0 s / whole answer in one chunk. Burst rule: one 160 ms block fade, no per-word animation.
- Very fast streams (> 2000 graphemes/s): CatchUp nearly always; effects effectively off; that is intended. Very slow streams (< 2 tokens/s): each word animates; caret blinks between; stall at
stall_softhands wording to the status line. - Huge outputs (> 100 KB). Transcript virtualises settled blocks; reveal cost bounded by the 64-unit budget.
- Tool interleaving. Reveal pauses at the block boundary; the pacer's buffer is flushed before the tool row appears so text never trails behind a later tool row.
- Background tab. Reveal does nothing while hidden; on focus the received text appears with one block fade (no replay of the "typing").
- Terminal surface. Only
line-commit,typewriter,instant; caretsblock/underscore.
Notes for AI
- Import
TextRevealfromoxyn_dioxusand includeSTATUS_TEXT_CSSplus the token stylesheet once. - A GPUI version exists:
TextRevealElinoxyn_gpui. - Props to set first:
text,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.