Skip to content
Back

Streaming markdown

Markdown that renders correctly while it streams: held-back partial markers, open code fences that grow, tables that wait for whole rows, a caret, and stop or error states.

oxyn add streaming-markdown
MCP
Waiting for the first token…
Dioxus
rsx! {
    StreamingMarkdown {
        text: reply,
        elapsed_ms: now - started,
        first_token_ms: 600,
        on_cite: move |n: u32| sources.highlight(n),
    }
}

Rendered from Rust at build time · goes live when visible

When to use

  • Agent answers are documents: headings, lists, tables, math, and above all code the user will copy, run or apply.
  • While streaming, the renderer must never flash raw syntax, never reflow what the user is reading, and never hand the user a half-written code block as if it were done (copy disabled until the fence closes; Run and Apply only on complete blocks).
  • Every product renders markdown with copy buttons (note 04: "Markdown/code/table rendering w/ copy — All"); the differentiators are the code block's actions — Conductor's Run button on bash snippets with inline output, Claude desktop's "Fix this one / Apply fixes", ChatGPT code blocks with Preview (notes 03, 04, 08) — and the streaming Discipline Codex and MonoCode document in source (mutable tail, per-block repair; note 08).
  • A code block explicitly says to use a separate text-stream component for code still arriving (note 12): we make that one component with two phases instead.

When not to use

Installation

Streaming markdown 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 streaming-markdown
Rust
use crate::oxyn::{StreamingMarkdown, Markdown, STATUS_INDICATOR_CSS};

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

Usage

Dioxus · rust
rsx! {
    StreamingMarkdown {
        text: reply,
        elapsed_ms: now - started,
        first_token_ms: 600,
        on_cite: move |n: u32| sources.highlight(n),
    }
}

Examples

Streaming

Headings, lists, code, a table and citations arriving.

Waiting for the first token…
Code
rsx! {
    StreamingMarkdown {
        text: reply,
        elapsed_ms: now - started,
        first_token_ms: 600,
        on_cite: move |n: u32| sources.highlight(n),
    }
}

Stopped

Stopped mid-reply: what arrived stays.

Waiting for the first token…
Stopped · the reply above is partial
Code
rsx! {
    StreamingMarkdown {
        text: reply,
        elapsed_ms: now - started,
        phase: "stopped",
        first_token_ms: 600,
        on_cite: move |n: u32| sources.highlight(n),
    }
}

Error

Connection dropped with Retry.

Waiting for the first token…
Code
rsx! {
    StreamingMarkdown {
        text: reply,
        elapsed_ms: now - started,
        phase: "error",
        first_token_ms: 600,
        on_cite: move |n: u32| sources.highlight(n),
    }
}

Instant

Everything at once (Oxyn plus).

Waiting for the first token…
Code
rsx! {
    StreamingMarkdown {
        text: reply,
        elapsed_ms: now - started,
        first_token_ms: 600,
        on_cite: move |n: u32| sources.highlight(n),
    }
}

API reference

StreamingMarkdown

PropTypeDefaultDescription
textrequiredString—Full text the model will send.
elapsed_msu64u64::MAXMilliseconds since the stream started.
cpsf32140.0Characters per second (0 = instant).
first_token_msu64Default::default()Delay before the first token (waiting shimmer).
phaseString"streaming"`streaming` · `stopped` · `error` (stops at what arrived).
caretbooltrueShow the caret.
revealString"fade"`fade` · `none`.
active_citeOption<u32>Default::default()Highlighted citation.
on_citeEventHandler<u32>—A citation chip was pressed.

Markdown

PropTypeDefaultDescription
textrequiredString—Source.
caretboolDefault::default()Streaming caret at the end.
active_citeOption<u32>Default::default()Highlighted citation.
on_citeEventHandler<u32>—A citation chip was pressed.

Read from the Rust signature and doc comments.

Keyboard interactions

KeyAction
TabCitation chips, links, code copy

Accessibility

  • The container is aria-busy while streaming; the caret is aria-hidden.
  • Partial markers (**, `, [1) are held back so screen readers never hear them.
  • Citation chips are buttons named “Source n”.
From the spec
  • Rendered markdown uses real semantics: headings are headings (levels offset by the host so an answer's # is not the page's h1 — proposed default offset +2), lists are lists, tables have header cells and a caption ("Table, 84 rows, 5 columns"), task-list checkboxes are read-only checkboxes.
  • Code block: a region/group labelled "Rust code, 312 lines" (Arc labels its block "hello.ts source code", note 12); the pre is focusable for keyboard scrolling; Copy "Copy code" → "Copied"; Wrap is a toggle button (aria-pressed); Show all has aria-expanded + aria-controls; Run "Run snippet" / "Stop snippet"; Apply "Apply to auth.rs".
  • Streaming: aria-busy="true" on the message while open; code blocks in Streaming expose "Code block, writing" and their actions as disabled with the reason as description.
  • Announcements (polite, composer live region): "Snippet finished, exit 0" / "Snippet failed, exit 1" (assertive), "Applied to auth.rs, 12 additions, 3 deletions", "Apply conflict" (assertive).
  • Contrast: syntax themes are checked so every token colour ≥ 4.5:1 on the code background in both themes (Codex corrects pale custom theme colours automatically, note 08 — we apply the same contrast floor at token load); inline code background ≥ 3:1 is not required, text contrast is.
  • Math: exposes its LaTeX source as the accessible name until a MathML path exists on that platform.
  • Diagrams: the source code is the accessible alternative ("Diagram, flowchart. Show source").
  • Reduced motion: §5 last row.
  • Keyboard: inside a focused code block, ⌘/Ctrl+C with no selection copies the whole block (proposed); w toggles wrap when the block is focused (proposed, listed in the ? help).

Motion & interaction

  • Fence opens: code chrome (header + 1-line body) fades in 120 ms; the block reserves 1 line, then grows per committed line (line-commit 80 ms fade, text-reveal §4). No per-token effects in code.
  • Language label: "…" → "rust" crossfade 120 ms when the info string completes.
  • Streaming window: at 40 lines the block stops growing; the header line count rolls (dur.digit.roll); a 24 px top fade mask indicates hidden earlier lines.
  • Complete: final highlight pass applies; actions fade in 120 ms (stagger 30 ms); copy icon enables (opacity 40 % → 100 %). If the block was windowed it collapses to 20 lines (200 ms, anchored).
  • Copy: copy ✓ morph (message-bubble §4 timings: 160 ms, hold 1500 ms); label "Copy" → "Copied" rolls (Arc rolls its toggle labels, note 12).
  • Wrap toggle: lines re-wrap without animation (animating re-wrap is unreadable); the toggle icon swaps; the scroll position inside the block keeps the first visible line.
  • Show all / Collapse: height spring (dur.collapse), chevron rotates 180°, label rolls.
  • Run: ▶ → ■ morph (160 ms spring.snap, same as send control); output panel unfolds (200 ms); exit chip enters with dur.row.enter; success ✓ holds then rests; failure tone fades 200 ms, no shake.
  • Apply: button → 12 px loader → ✓ "Applied +12 −3" (diff numbers roll); Undo stays 10 s with a shrinking 2 px underline as its timer (proposed).
  • Diagram render: code view crossfades to the diagram (200 ms); height change anchored.
  • Table: column widths that grow while streaming animate with spring.snap 160 ms (text-reveal); "Show all rows" unfolds 200 ms.
Timing
TransitionDurationDelayEasing / springStaggerFrame rate
Code chrome enter120 ms0ease.out—60 Hz
Line commit (code)80 ms fade—linear—30 Hz (text-reveal)
Tail-line re-highlight≤ 1 per 100 ms—none (instant colour)——
Language label swap120 mson info-string endease.out—60 Hz
Line count roll280 ms (dur.digit.roll)—ease.out30 ms right → left30 Hz
Actions enter on complete120 ms0ease.out30 ms60 Hz
Window → collapsed (on complete)200 ms0spring.snap—60 Hz
Show all / collapse200 ms0spring.snap—60 Hz
Copy ✓ / hold / revert160 / 1500 / 160 ms0ease.out—60 Hz
Run ▶ → ■160 ms0spring.snap—60 Hz
Output panel unfold200 ms0ease.out—60 Hz
Applied ✓ + diff stats roll160 ms + 280 ms0spring.snap / ease.out—60 Hz
Undo timer underline10 000 ms0linear—15 Hz
Diagram code → render200 mson close + render timeease.in-out—60 Hz
Table column grow160 ms—spring.snap—60 Hz
Reduced motioneverything above → 0–80 ms opacity crossfades; heights snap; digits swap; Undo timer shown as static "Undo (10 s)" text counting at 1 Hz; code lines appear per line without fade—linearnoneon change

Responsive behaviour

  • Tables and code scroll horizontally inside their own frames.
Edge cases (spec)
  • Huge outputs (> 100 KB per message): settled blocks virtualise (messages.md §4.1); highlight caps §3.3; the in-flight reveal budget stays at 64 units (text-reveal).
  • Fence inside a fence / tilde fences / 4+ backticks: follow CommonMark fence-length rules; the repair pass never closes a fence early (MonoCode's remend skips fences, note 08).
  • Code with very long lines: no wrap by default; horizontal scroll inside the block; wrap toggle persists per session (proposed); a 12 px fade on the overflowing edge.
  • Tabs and mixed indentation: tab width 4 (token); visible-whitespace off.
  • RTL: prose mirrors; code blocks, inline code, math and tables of numbers stay LTR (bidi isolates); list bullets move to the right; the code header's actions stay trailing in reading direction.
  • CJK: prose line-breaking follows the platform; code font fallback must include CJK glyphs at mono width ×2 (cell alignment in terminal surface).
  • Tiny widths (< 320 px): code header shows icon-only Copy; line numbers hidden; tables become "Show table" disclosure that opens a full-width sheet.
  • Dense IDE panels: markdown/compact + code-block/file; Apply / Open in editor are primary.
  • Touch: code blocks scroll horizontally with the finger without scrolling the transcript (axis lock after 8 px); Copy 44 px hit area.
  • Slow networks: a fence open for > stall_soft keeps the "Writing" header and loader; the composer status handles "Still working".
  • Very fast streams: whole blocks arrive at once (text-reveal CatchUp) — the code block goes Opening → Complete in one frame: chrome and body appear together, no window phase.
  • Interrupted mid-fence: Truncated (§2.3); copying works; Run/Apply disabled with the reason.
  • Unknown / unsafe languages for Run: Run hidden; never infer runnable from content.
  • Math: rendered on close; render failure → raw LaTeX in mono with a dim "Couldn't render" note. The math layout engine for GPUI is an open question (see Gaps in §10).
  • Images in markdown: placeholder box (text-reveal §5); broken image → alt text in a bordered box; remote images can be blocked by host policy ("Image blocked · Load").
  • Malicious markdown: links with mismatched text/destination show the real domain in the hover tooltip; raw HTML off by default.

Notes for AI

  • Import StreamingMarkdown, Markdown from oxyn_dioxus and include STATUS_INDICATOR_CSS plus the token stylesheet once.
  • A GPUI version exists: MarkdownEl in oxyn_gpui.
  • Props to set first: text, text.
  • 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