Controls and surfaces
streaming-text
Text that grows as it arrives, with a caret while it is arriving, that is never read out word by word: it is announced once, when it is finished.
When to use it
A reply from a model, a transcript or a log line that streams in. Pass the text so far and whether more is coming. It must not sit inside a live region (a thread is aria-live="off"); say "Writing a reply" through a status-line while it streams. For text that is already complete use a plain element; for a headline that animates in use text-reveal.
Add it
npx shadcn@latest add @rivier-ui/streaming-textThe registry is named once in components.json: see Installation.
Example
Import it from @/components/ui/streaming-text.
<MessageContent>
<StreamingText text={reply} streaming={isStreaming} announceWhenDone onDone={saveReply} />
</MessageContent>
// A shorter spoken form, and words that fade in as they land
<StreamingText text={reply} streaming={isStreaming} reveal="word" announceWhenDone="Three places found. The nearest is ten minutes away." />
// The project's own renderer (Markdown, for example)
<StreamingText text={reply} streaming={isStreaming}>{(text) => <Markdown>{text}</Markdown>}</StreamingText>What it needs
A client component: it uses state, effects or browser behaviour. No packages beyond React.
It imports
Source
The whole file. Once copied it is yours: the registry item holds the same text.
"use client";
/**
* @name streaming-text
* @category ui
* @description Text that grows as it arrives, with a caret while it is arriving, that is never read out word by word: it is announced once, when it is finished.
* @when A reply from a model, a transcript or a log line that streams in. Pass the text so far and whether more is coming. It must not sit inside a live region (a thread is `aria-live="off"`); say "Writing a reply" through a status-line while it streams. For text that is already complete use a plain element; for a headline that animates in use text-reveal.
* @example
* <MessageContent>
* <StreamingText text={reply} streaming={isStreaming} announceWhenDone onDone={saveReply} />
* </MessageContent>
*
* // A shorter spoken form, and words that fade in as they land
* <StreamingText text={reply} streaming={isStreaming} reveal="word" announceWhenDone="Three places found. The nearest is ten minutes away." />
*
* // The project's own renderer (Markdown, for example)
* <StreamingText text={reply} streaming={isStreaming}>{(text) => <Markdown>{text}</Markdown>}</StreamingText>
*/
import { useEffect, useEffectEvent, useRef, type ComponentProps, type ReactNode } from "react";
import { announce } from "@/lib/announce";
import { cn } from "@/lib/cn";
export type StreamingTextProps = Omit<ComponentProps<"span">, "children"> & {
/** The text so far. */
text: string;
/** Whether more is coming. While true the element is `aria-busy` and shows the caret. */
streaming?: boolean;
/**
* Said once through the shared live region when streaming ends: `true` says the whole text, a string says
* that instead (a shorter spoken form of a long reply). Leave it out when the project announces the reply
* some other way. Text that was complete when it was first shown is not announced.
*/
announceWhenDone?: boolean | string;
/** Called once when `streaming` goes from true to false, with the finished text. */
onDone?: (text: string) => void;
/** The caret after the last word while streaming. Default true. */
caret?: boolean;
/** "word": each word fades in as it lands (opacity only, off under reduced motion). The text is in the page either way. Default "none". */
reveal?: "none" | "word";
/** Render the text yourself (Markdown, links). `reveal` then does not apply. */
children?: (text: string) => ReactNode;
};
/**
* Nothing here is a live region, on purpose: a screen reader that announced every arriving word would be
* unusable. The element only marks itself busy; the one announcement is made when the text is whole.
* Arriving text never takes or moves focus.
*/
export function StreamingText({ className, text, streaming = false, announceWhenDone, onDone, caret = true, reveal = "none", children, ...props }: StreamingTextProps) {
const wasStreaming = useRef(streaming);
const finish = useEffectEvent((): void => {
onDone?.(text);
if (announceWhenDone === true) announce(text);
else if (typeof announceWhenDone === "string") announce(announceWhenDone);
});
useEffect(() => {
if (wasStreaming.current && !streaming) finish();
wasStreaming.current = streaming;
}, [streaming]);
return (
<span data-slot="streaming-text" data-streaming={streaming ? "" : undefined} aria-busy={streaming || undefined} className={cn("wrap-anywhere whitespace-pre-wrap", className)} {...props}>
{children ? children(text) : reveal === "word" ? <Words text={text} /> : text}
{streaming && caret ? (
<span
aria-hidden="true"
data-slot="streaming-text-caret"
className="ms-0.5 inline-block h-[1em] w-[0.5em] translate-y-[0.15em] animate-pulse rounded-control bg-current opacity-70 motion-reduce:animate-none"
/>
) : null}
</span>
);
}
/**
* The text as words and the spaces between them. A word keeps its key as the text grows, so only a word
* that has just landed is mounted, and only that one fades in. The words are real text in the page.
*/
function Words({ text }: { text: string }) {
const pieces = text.split(/(\s+)/);
return (
<>
{pieces.map((piece, index) =>
index % 2 === 1 || piece === "" ? (
piece
) : (
<span key={index} className="animation-duration-(--duration-slow) animate-in fade-in-0 motion-reduce:animate-none">
{piece}
</span>
),
)}
</>
);
}