Skip to content
NewYour data: charts, lists and meters that take your records
<hf-stream>Custom elementUltracode

Streaming reply

Streaming reply where each word resolves out of noise behind a glowing block caret, with a dotted tokens-per-second sparkline.

View as Markdown
<hf-stream>

Trypress Stop, then Regenerate.

Demo data

The streaming, its timing and the tokens-per-second figures are simulated; only the text can be set. It cannot show your own data yet, so use it as a template: replace the invented data in its source before it shows anything real. See Your data.

Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

Loading <hf-stream>
Props
textremounts
delayremounts
loopremounts
<HfStream delay={500} loop />

Installation

pnpm dlx shadcn@latest add @lumesec/hf-stream
First timeRegister the @lumesec registry once, or install by URL

Adds @lumesec to your components.json:

pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json

Or skip the setup and install by URL:

npx shadcn@latest add https://elements.lumesec.ai/r/hf-stream.json

Usage

import { HfStream } from "@/components/lumesec/hf-stream";

export function Example() {
  return (
    <HfStream loop />
  );
}

Behaviour

Each token resolves out of a patch of noise as it arrives, a glowing block caret rides the end of the text, and a dotted sparkline tracks tokens per second.

API reference

Attributes

textReact proptextTypestring

Text to stream. Defaults to a built-in sample paragraph. Split at whitespace; each word counts as one token. Re-read on each start.

delayReact propdelayTypenumberDefault500

Milliseconds before the first stream starts after connect.

loopReact proploopTypebooleanDefaultfalse

Presence attribute. Starts again 3.5 s after a stream completes; not after Stop.

Events

Events bubble and cross the shadow boundary unless the description says otherwise.

startReact proponStartDetail{}

Fires when a stream starts.

doneReact proponDoneDetail{ tokens: number, stopped: boolean }

Fires when a stream completes or is stopped.

Methods

Call them on the element, for example through a React ref.

start(): Promise<void>

Clears the text and streams it again, cancelling a stream in progress.

stop()

Stops the current stream and fires done with stopped: true. Also cancels a pending automatic start; does nothing else while no stream runs.

Accessibility

  • The reply text is an aria-live="polite" region with aria-busy="true" while it streams, so screen readers can read the reply once instead of word by word.
  • The canvas and the sparkline are aria-hidden.
  • The Stop / Regenerate control is a native button.
  • Reduced motion: words arrive every 10 ms without the decode shimmer or fade-in, the avatar and caret do not pulse, and the caret disappears at once when the stream ends.

Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from --lumesec. See Theming.

This component reads --border, --foreground, --lumesec, --muted and --muted-foreground.

To restyle only LumeSec elements, set the matching --ui-* overrides: --ui-accent, --ui-border, --ui-fg, --ui-font, --ui-mono, --ui-muted and --ui-raised.

Notes

  • Streaming is simulated from text with random delays. It starts automatically after delay; there is no attribute to turn that off.
  • The speaker name Assistant is fixed text.
  • Removing the element from the page stops the stream and any loop restart; inserting it again starts a new stream after delay.

Was this page helpful?