Streaming text
An answer that arrives word by word, each word fading in from a 3 px blur, with a round caret at the end while more is coming. It shows real progress; never fake it for text you already have.
Usage
Use it when
- An assistant reply that is generated while the person waits: show words as they arrive from the server.
- Right after thinking ends: the thinking row settles, then the answer streams in under it.
Use something else when
- Waiting before the first word exists: use Thinking.
- Text you already have in full (a saved answer, a help article): use Prose. Show it at once; typing it out only slows people down.
- A short status that changes (Saving, Saved): use Text morph.
- Loading the layout of a page: use Skeleton.
Where it goes. Inside the .bubble of a msg--ai chat message, or in any reading block that is being generated (a summary at the top of a report). The actions row of the message stays hidden until streaming ends.
Examples
import { streamText } from 'lampung-design-system/js';
bubble.setAttribute('aria-busy', 'true');
actions.hidden = true;
await streamText(bubble, fullText, { wordMs: 40 }); // or append words yourself as they arrive
bubble.removeAttribute('aria-busy');
actions.hidden = false;<div class="msg msg--ai">
<div class="thinking" data-lds-thinking role="status"><span class="dotgrid" aria-hidden="true"></span><span class="shimmer">Reading your notes</span><span class="thinking__time"></span></div>
<div class="bubble"></div>
</div>
<script type="module">
import { thinkingDone, streamText } from 'lampung-design-system/js';
// when the first token arrives:
thinkingDone(msg.querySelector('.thinking'), 'Read 3 pages of your notes');
await streamText(msg.querySelector('.bubble'), text);
</script>Class summary
Class summary
<div class="card" style="max-width: 560px;">
<p class="card__title">Class summary</p>
<p class="card__sub stream is-streaming" id="st-c" style="margin-top: 8px;"></p>
<button class="btn btn--plain btn--sm" style="margin-top: 8px; margin-left: -10px;" onclick="this.hidden = true; import('../../js/lds.js').then((m) => m.streamText(document.getElementById('st-c'), 'Most students finished the quiz in under 20 minutes. Question 7 was missed by 18 of 30, so it is worth reviewing on Monday.'));">Generate summary</button>
</div>Anatomy
| Part | What it is |
|---|---|
.stream | The element receiving words (added by streamText). |
.stream.is-streaming | While words are still coming: draws an 8 px round caret after the last word, blinking each second. |
.stream__w | One arrived word. Fades from 3 px blur and transparent over 360 ms. |
States
| State | How |
|---|---|
streaming | .stream.is-streaming: words arriving, caret shown, aria-busy="true" on the container. |
done | Caret removed, aria-busy removed, actions revealed. |
stopped | If the person stops generation, call it done where it is and add a message meta line "Stopped". |
Motion and microinteractions
- Each word:
lds-word-in, fromopacity: 0andblur(3px)to sharp over 360 ms on--ease-enter. No movement, so lines never jump while reading. - Pace:
streamTextadds one word everywordMs(40 ms by default). When you stream from a server, append words as they come; do not add an artificial delay on top. - Caret: an 8 px dot after the last word, blinking with
lds-caret(1 s, stepped). It disappears the moment the text is complete. - Interruption: calling
streamTextagain on the same element clears it and starts over; words already faded stay sharp. - Reduced motion: words appear at once (no delay between them, 1 ms fade) and the caret shows without blinking.
Accessibility
- Set
aria-busy="true"on the message while it streams and remove it at the end, so a screen reader in therole="log"reads the whole answer once instead of word by word. - Do not move focus to the answer while it streams; the person may be typing the next question.
- The caret is decoration (a pseudo-element); nothing to hide.
Do and don't
Do
- Stream only text that is really being generated.
- Pair with thinking for the wait before the first word.
- Reveal copy and retry actions only after the end.
Don't
- Type out text you already have to make it feel smart.
- Animate words upward or scale them; reading lines must stay still.
- Auto-scroll the conversation while the reader has scrolled up; show Latest instead (chat layout).
Behavior and code
Plain HTML. streamText(el, text, { wordMs = 40 }) from js/lds.js adds stream is-streaming to el, clears it, appends each word as a .stream__w span, and resolves its promise when done (removing is-streaming). With live tokens, add stream is-streaming yourself, append <span class="stream__w">word</span> per word, and remove is-streaming at the end.
React. From lampung-design-system/react.
import { Thinking } from 'lampung-design-system/react';
{phase === 'thinking' && <Thinking label="Reading your notes" startedAt={startedAt} />}
<div className={`bubble stream${phase === 'streaming' ? ' is-streaming' : ''}`} aria-busy={phase === 'streaming'}>
{words.map((w, i) => <span key={i} className="stream__w">{w} </span>)}
</div>