Components/CodeStream

CodeStream

A code block with a filename header that streams or reveals code.

VerifiedSince 0.3.9

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 streaming for code arriving from a model and let the component pace it; use revealedLines only when the host owns the cadence (a scripted replay, a log).
  • In streaming mode the box grows with its lines; set minHeight to the final height when the page below must not move, and reserve for 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 TxCodeBlock to match TxStreamMarkdown fences; 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-scripts only 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-preview when 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

PropTypeDefaultDescription
codestring—The source. Required.
langstring''Shiki language id; empty skips highlighting and never loads Shiki.
filenamestring—Header filename, in the mono face.
langLabelstring—Language label beside the filename, e.g. TypeScript.
revealedLinesnumber—Lines revealed, clamped to range; omit or pass -1 for all.
streamingboolean—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.
wordMsnumber24Streaming mode: releases one word every wordMs.
maxLagMsnumber600Streaming mode: no word shows later than this after it arrives.
drainMsnumber320Streaming mode: once streaming turns false, releases the rest within this.
pauseMsnumber400Streaming mode: reports paused after this long without a new word.
reservebooleanfalseStreaming mode: holds the full height while complete code plays back; ignored while streaming.
pacedbooleantrueStreaming mode: false shows each word as it arrives, still animated; TxStreamElement passes it to pace parts itself.
appearbooleanfalseStreaming mode: code present at mount enters too. Read at mount.
caretbooleantrueA still end-of-line marker with revealedLines, the Tuff caret in streaming mode; off removes it at once.
lineNumbersbooleantrueShows line numbers.
theme'light' | 'dark' | 'auto''auto'Highlight theme; 'auto' follows the document root's data-theme or .dark.
copyablebooleantrueRenders the copy button.
copyLabelstring'Copy'Copy button text; localize it together with copiedLabel.
copiedLabelstring'Copied'Text shown after a successful copy.
previewablebooleantrueOffers a "Preview" toggle for html, svg and xml code once it stops arriving; never while streaming or in diff mode.
autoPreviewbooleanfalseOpens on the rendering as soon as the code settles; the reader can switch back to the source.
previewScriptsbooleanfalseLets the previewed page run its own scripts; the frame stays an opaque-origin sandbox with no network.
previewLabelstring'Preview'Toggle text.
codeLabelstring'Code'Toggle text while the rendering shows.
frameLabelFormatter(lang: string) => string(lang) => `${lang} preview` Accessible name of the preview frame.
minHeightnumber | string—Floor for the code area; defaults to the full listing's height.
diffCodeDiffRow[]—Unified diff rows; renders them with an added/removed tally. The copy button still yields code.

Events

EventPayloadDescription
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

NameScopeDescription
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

NameTypeDescription
stateStreamStateThe streaming-mode state; idle in the other modes.
replay() => voidStreaming mode: plays the code again from the first word.
skip() => voidStreaming mode: shows everything now, without entrances.

Types

CodeDiffRow

FieldTypeDescription
contentstringThe row's text, without a + / - marker.
kind'context' | 'added' | 'removed'Defaults to 'context'.
numbernumberGutter number; a removed row and its replacement usually share one. Omit to leave it blank.

Overview

  • Setting streaming (true or false) without revealedLines or a non-empty diff selects 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 sandbox iframe without allow-same-origin. Its document is written as an outer srcdoc: the policy <meta> sits in the outer document and the previewed code is embedded as an escaped inner srcdoc, so a " or a <head> inside the code cannot move the policy. The policy is default-src 'none' with only inline styles and data:/blob: images and media allowed; script-src is 'none' unless previewScripts is set, which makes it 'unsafe-inline'.
  • Under reduced motion no line or word entrance plays: revealedLines still 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. TxStreamCode is 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