# Streaming reply
> Streaming reply where each word resolves out of noise behind a glowing block caret, with a dotted tokens-per-second sparkline.
- Element: `<hf-stream>`
- React: `import { HfStream } from "@/components/lumesec/hf-stream"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-stream.json
- Page: https://elements.lumesec.ai/components/pixel-hd/stream



Live preview: https://elements.lumesec.ai/view/hf-stream

```html
<hf-stream loop></hf-stream>
```

## Playground

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

## Installation

```bash
npx shadcn@latest add @lumesec/hf-stream
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/hf-stream.json
```

## Usage

React:

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

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

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/hf-stream.js"></script>

<hf-stream loop></hf-stream>
```

## 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

| Attribute | React prop | Type      | Default | Description                                                                                                                         |
| --------- | ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `text`    | `text`     | `string`  | —       | Text to stream. Defaults to a built-in sample paragraph. Split at whitespace; each word counts as one token. Re-read on each start. |
| `delay`   | `delay`    | `number`  | `500`   | Milliseconds before the first stream starts after connect.                                                                          |
| `loop`    | `loop`     | `boolean` | `false` | 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.

| Event   | React prop | Detail                                 | Description                                  |
| ------- | ---------- | -------------------------------------- | -------------------------------------------- |
| `start` | `onStart`  | `{}`                                   | Fires when a stream starts.                  |
| `done`  | `onDone`   | `{ tokens: number, stopped: boolean }` | Fires when a stream completes or is stopped. |

### Methods

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

| Method                   | Description                                                            |
| ------------------------ | ---------------------------------------------------------------------- |
| `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`.        |

## Accessibility

* The reply text is in an `aria-live="polite"` region and grows 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](/docs/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 `Claude` is fixed text.