smooth-stream-text weekly downloads statistics

smooth-stream-text

Live playground · Documentation · Examples

Adaptive text-stream smoothing for AI chat interfaces. Keep your existing Markdown renderer and pace incoming text with a zero-dependency headless core. React, Vue, Svelte and Web Component integrations are included; a fade-in reveal is optional.

When a language model answers, the chunks arrive unevenly: one word, then twenty at once, then a pause while the server thinks. Rendering each chunk the moment it lands means the text stutters, and the eye reads the stutter before it reads the words.

smooth-stream-text sits between your transport and your renderer. You hand it the text received so far and whether the answer is finished; it hands back a prefix that grows at an even, adaptive rate, which you render exactly as before. It works with any provider (OpenAI, Anthropic, Google, your own backend) because it only sees text.

• A real pacing controller. Not a fixed characters-per-second you tune per model - the rate follows from holding a constant distance behind the live text, so it adapts to whatever is feeding it. • Headless first. Take the smoothed string and render it however you already do. The ready-made component is a convenience, not the only way in. • Zero runtime dependencies. The core is pure logic and runs in Node, which is why its timing is tested without a browser and without waiting. • Every framework. React, Vue, Svelte and a Web Component - which also covers Angular, Solid, Qwik, Astro and plain HTML. Each framework is an _optional_ peer dependency. • Careful about the text itself. The text grows a character at a time, or a whole word at a time if you prefer - in Chinese, Japanese and Thai too - and never stops inside a **, a half-written link or an emoji, so a markdown renderer downstream never flashes broken syntax.

It fits when text arrives in bursts and you want it to read as a steady flow, you already have a renderer (react-markdown, Streamdown, marked, your own), and history must appear at once while only new answers are paced.

It does not fit when you only render static Markdown, need transport features (retries, reconnects), want a CSS typing effect for a heading, or already pace text in another layer such as the AI SDK's smoothStream() and are happy with it: two layers add their delays. The core runs anywhere JavaScript runs, but only the web bindings are built and tested. Choosing an approach compares the alternatives.

Install

Full documentation, with a guide per framework and runnable examples: smooth-stream-text.vercel.app/docs. For tools and coding assistants, llms.txt lists every page as plain Markdown, and the package ships INTEGRATION.md, a short guide readable offline in node_modules/smooth-stream-text/. An optional Agent Skill for coding agents installs with npx skills add crmapache/smooth-stream-text.

Quick start - headless (the main path)

Most chat UIs parse markdown themselves and render it with their own components. Those only need the smoothed string:

That is the whole integration. Feed it your accumulated answer, render what comes back. useSmoothText re-renders only when the visible text or the phase changes, at most once per animation frame while text appears. That can be more often than chunks arrive, so if your Markdown rendering is expensive, see the benchmarks. useSmoothStream takes the same arguments and returns the full state as well - the backlog, the current rate, the source - for debugging and charts.

One hook serves a whole conversation. A message that is already done when it first arrives is history and appears at once. A different message starts over. done closes whichever answer is current, including when its last chunk lands after done was already set.

If your transport hands you deltas and you would rather not accumulate them:

Recipes

AI SDK useChat with react-markdown

If the server already runs smoothStream() from the AI SDK, the two delays add up. Pick one: the server-side transform sends evenly sized chunks at a fixed delay, this package adapts the rate on the client to whatever actually arrives.

Streamdown

Streamdown renders markdown and can fade words in by itself. Let it own the animation and use this package only for pacing - two layers animating the same words would fight.

Vue and Nuxt

done accepts a boolean, a ref or a getter. Both work under Nuxt's server rendering: finished text is in the server output, and nothing is scheduled on the server.

Svelte 5 and SvelteKit

Actions do not run on the server, so an element with the action is empty in the server output and fills in on the client. For server-rendered history, use the store.

Adding the wave to your own markup

The reveal is a separate layer, so you can hang it on the pieces your renderer produces - paragraphs, list items, headings, table cells:

RevealProvider shares one wave across everything beneath it, so the stagger stays continuous when an answer is split into separate blocks. Its settings can change at any time, and every Reveal already on screen follows. Reveal takes a string and animates only what was appended since the last render. Other props - id, aria-*, style, a ref - go to the element it renders.

Two behaviours make this safe with a parser that rebuilds its tree:

• Mounting seeds, it does not animate. A freshly created Reveal treats its text as already settled, so a recreated node shows its text instantly instead of replaying it. Changing as moves the text to the new element the same way. • A non-extension is a silent reseed. If the text is no longer an extension of what was shown - the parser re-split a paragraph, or moved text between blocks - it reseeds rather than re-animating text the reader already saw.

Ready-made component

When you are rendering plain text and want both layers in one element:…

Description from the npm listing.