CodeStream
A code block with a filename header that streams or reveals code.
Usage
Streaming
Pass the code received so far as code and set streaming; the component releases it word by word at a steady pace.
Loading demo...
Line-by-Line Reveal
The host advances revealedLines; the component owns the transition and the caret.
Loading demo...
Full Listing
Without revealedLines and streaming, the whole listing shows.
Loading demo...
Rendered Preview
Once html, svg or xml code stops arriving, a "Preview" toggle appears in the header and renders it in a sandboxed iframe, and the same button returns to the source; it never appears while streaming or in diff mode, and auto-preview opens the rendering as soon as the code settles.
Loading demo...
Unified Diff
diff renders a unified diff; a removed row and the added row replacing it share a number, so numbers are given per row.
Loading demo...
Best Practices
- Use
streamingfor code arriving from a model and let the component pace it; userevealedLinesonly when the host owns the cadence (a scripted replay, a log). - In streaming mode the box grows with its lines; set
minHeightto the final height when the page below must not move, andreservefor playback of complete code. - When the language is uncertain, omit
lang: plain text is always correct. - Put long listings in an outer scroll container; the code area scrolls only horizontally and its height follows content.
- Use
TxCodeBlockto matchTxStreamMarkdownfences; use this component for a filename header, line numbers, and a line-by-line reveal. - A previewed page does not run scripts by default. Set
preview-scriptsonly when the host trusts the page; even then the frame has no same-origin access and no network, so a script can draw but cannot reach the host. - Use
auto-previewwhen the model was asked for a page; leave it off when the code is only a snippet on show, where the reader should see the source first.
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
code | string | — | The source. Required. |
lang | string | '' | Shiki language id; empty skips highlighting and never loads Shiki. |
filename | string | — | Header filename, in the mono face. |
langLabel | string | — | Language label beside the filename, e.g. TypeScript. |
revealedLines | number | — | Lines revealed, clamped to range; omit or pass -1 for all. |
streaming | boolean | — | Streaming mode: the source is live; false shows the code at once and allows replay(). |
reveal | 'aurora' | 'hue' | 'blur' | 'languid' | 'none' | 'aurora' | Streaming mode: how a word enters. Code keeps its syntax color: aurora equals blur, hue is a fade. |
wordMs | number | 24 | Streaming mode: releases one word every wordMs. |
maxLagMs | number | 600 | Streaming mode: no word shows later than this after it arrives. |
drainMs | number | 320 | Streaming mode: once streaming turns false, releases the rest within this. |
pauseMs | number | 400 | Streaming mode: reports paused after this long without a new word. |
reserve | boolean | false | Streaming mode: holds the full height while complete code plays back; ignored while streaming. |
paced | boolean | true | Streaming mode: false shows each word as it arrives, still animated; TxStreamElement passes it to pace parts itself. |
appear | boolean | false | Streaming mode: code present at mount enters too. Read at mount. |
caret | boolean | true | A still end-of-line marker with revealedLines, the Tuff caret in streaming mode; off removes it at once. |
lineNumbers | boolean | true | Shows line numbers. |
theme | 'light' | 'dark' | 'auto' | 'auto' | Highlight theme; 'auto' follows the document root's data-theme or .dark. |
copyable | boolean | true | Renders the copy button. |
copyLabel | string | 'Copy' | Copy button text; localize it together with copiedLabel. |
copiedLabel | string | 'Copied' | Text shown after a successful copy. |
previewable | boolean | true | Offers a "Preview" toggle for html, svg and xml code once it stops arriving; never while streaming or in diff mode. |
autoPreview | boolean | false | Opens on the rendering as soon as the code settles; the reader can switch back to the source. |
previewScripts | boolean | false | Lets the previewed page run its own scripts; the frame stays an opaque-origin sandbox with no network. |
previewLabel | string | 'Preview' | Toggle text. |
codeLabel | string | 'Code' | Toggle text while the rendering shows. |
frameLabelFormatter | (lang: string) => string | (lang) => `${lang} preview` | Accessible name of the preview frame. |
minHeight | number | string | — | Floor for the code area; defaults to the full listing's height. |
diff | CodeDiffRow[] | — | Unified diff rows; renders them with an added/removed tally. The copy button still yields code. |
Events
| Event | Payload | Description |
|---|---|---|
copy | (code: string) | Fires after a successful copy. |
complete | — | Fires once when revealedLines reaches the last line; not when mounted complete, nor in streaming mode. |
state-change | (state: StreamState) | Streaming mode: fires when the state changes. |
done | — | Streaming mode: fires once per play-through. |
Slots
| Name | Scope | Description |
|---|---|---|
header | — | Replaces the filename and language label. |
actions | — | Custom controls before the copy button. |
caret | { state } | Streaming mode: replaces the Tuff caret; rendered only while live. |
Exposed Methods
| Name | Type | Description |
|---|---|---|
state | StreamState | The streaming-mode state; idle in the other modes. |
replay | () => void | Streaming mode: plays the code again from the first word. |
skip | () => void | Streaming mode: shows everything now, without entrances. |
Types
CodeDiffRow
| Field | Type | Description |
|---|---|---|
content | string | The row's text, without a + / - marker. |
kind | 'context' | 'added' | 'removed' | Defaults to 'context'. |
number | number | Gutter number; a removed row and its replacement usually share one. Omit to leave it blank. |
Overview
- Setting
streaming(trueorfalse) withoutrevealedLinesor a non-emptydiffselects streaming mode; its pacing, states, and incremental reveal match StreamText. - With
revealedLines, the caret appears only while revealing (0 < revealedLines < total), still, at the end of the last line. - Removed rows take a hatched gutter marker and added rows a solid one, so the distinction never rests on red and green alone.
- Only Shiki-generated markup reaches
v-html, with the code text escaped; unhighlighted code is plain interpolation. - The preview frame is a
sandboxiframewithoutallow-same-origin. Its document is written as an outersrcdoc: the policy<meta>sits in the outer document and the previewed code is embedded as an escaped innersrcdoc, so a"or a<head>inside the code cannot move the policy. The policy isdefault-src 'none'with only inline styles anddata:/blob:images and media allowed;script-srcis'none'unlesspreviewScriptsis set, which makes it'unsafe-inline'. - Under reduced motion no line or word entrance plays:
revealedLinesstill reveals, streaming mode shows code as it arrives, and the caret rests.
Technologies
- Highlighting reuses
TxCodeBlock's lazy Shiki singleton: plain text renders first and color arrives asynchronously.TxStreamCodeis an alias of the same component. - Adapted from Beautiful UI (© 2026 Shane Levine, MIT).
- Source:
packages/tuffex/packages/components/src/code-stream/.
查看源码
packages/tuffex/packages/components/src/code-stream/index.ts