Skip to content
Browse documentation
whisk/ui

StreamingText

Render generated text as it arrives.

Overview

StreamingText renders an application-controlled prefix of prepared plain text. It preserves word and grapheme boundaries as a response arrives, optionally marks the most recently revealed words, and never starts a timer, reads a stream, parses Markdown, or announces each update.

Use when

Application-owned generated text is arriving incrementally.

Use instead

Use Text or Markdown for complete, stable content.

Usage

The deployment completed successfully.
import { prepareStreamingText } from "@smoothie-framework/whisk-core/streaming-text";
import { StreamingText } from "@smoothie-framework/whisk-react";

const response = prepareStreamingText([
  { text: "The deployment completed successfully." },
]);

<StreamingText
  text={response}
  revealedWordCount={response.wordCount}
  status="complete"
/>

Examples

Control the revealed prefix

Prepare the text once for its current source revision. Advance revealedWordCount from application state as words become available; StreamingText does not read a stream or run a timer.

The deployment

Response is still arriving.

import { useState } from "react";
import { prepareStreamingText } from "@smoothie-framework/whisk-core/streaming-text";
import { Button, StreamingText } from "@smoothie-framework/whisk-react";

const response = prepareStreamingText([
  { text: "The deployment completed successfully." },
]);

export function ResponsePreview() {
  const [revealedWordCount, setRevealedWordCount] = useState(2);
  const complete = revealedWordCount >= response.wordCount;

  return <>
    <StreamingText
      text={response}
      revealedWordCount={revealedWordCount}
      status={complete ? "complete" : "streaming"}
    />
    <Button onClick={() => setRevealedWordCount((count) => count + 1)}>
      Reveal next word
    </Button>
  </>;
}

Preserve a known code segment

Use source segments when an application already knows that part of the plain-text response is code. Segments must end on grapheme boundaries; StreamingText renders them as text and does not parse Markdown.

Run bun run build before opening a pull request.
import { prepareStreamingText } from "@smoothie-framework/whisk-core/streaming-text";
import { StreamingText } from "@smoothie-framework/whisk-react";

const response = prepareStreamingText([
  { text: "Run " },
  { text: "bun run build", kind: "code" },
  { text: " before opening a pull request." },
]);

<StreamingText
  text={response}
  revealedWordCount={response.wordCount}
  segmentStyles={{ 1: { weight: "medium" } }}
/>

Complete the response deliberately

Set status to complete when the transport ends, including when the visible word count already equals wordCount. Completion reveals trailing punctuation and whitespace and removes the decorative caret.

tsx
<StreamingText
  text={response}
  revealedWordCount={response.wordCount}
  status="complete"
  showCaret={false}
/>

Keep server and client boundaries identical

For server rendering, serialize the prepared snapshot and restore it with parsePreparedStreamingText on the client. Do not prepare the same source separately on both sides because locale data can vary by platform.

tsx
import {
  parsePreparedStreamingText,
  prepareStreamingText,
} from "@smoothie-framework/whisk-core/streaming-text";

// Server: include this JSON in application data.
const serialized = JSON.stringify(prepareStreamingText([{ text: responseText }], { locale: "en" }));

// Client: restore the server's exact word and grapheme boundaries.
const response = parsePreparedStreamingText(JSON.parse(serialized));

<StreamingText text={response} revealedWordCount={response.wordCount} />

Props

Component props

PropTypeDefaultDescription
textPreparedStreamingTextrequiredA snapshot made with prepareStreamingText. Re-create it when the source changes, not for every reveal count.
revealedWordCountnumberrequiredThe application-controlled visible word count. Values are clamped from 0 through text.wordCount.
statusstreaming | completecompleteShow an in-progress prefix and optional caret, or finish the text and reveal its trailing separators.
showCaretbooleantrueShow the decorative streaming caret. It has aria-hidden and appears only while status is streaming.
segmentStylesRecord<number, StreamingTextSegmentStyle>noneStyle source segments by index with text semantics, a textStyle, className, or inline style. It does not change token boundaries.
size | weight | color | alignTextSemanticPropsnoneApply a shared text treatment to the span. Use segmentStyles only when a known source segment needs distinct presentation.
native span propsHTMLAttributes<HTMLSpanElement>noneAdd an id, direction, data attribute, or application-owned semantics. StreamingText provides no live-region behavior itself.

Accessibility

StreamingText renders a span and intentionally has no role or aria-live behavior, so assistive technology is not asked to read every arriving word. Put a concise, stable progress message in an application-owned status region when people need to know that work is in progress. Keep the completed response as ordinary selectable text. The caret is decorative. Use the correct locale when preparing text so the word boundaries match the language being displayed, and do not use this component to turn untrusted Markdown or HTML into rich content.