flowdown

O(1) streaming markdown renderer for the AI era. Zero dependencies. ~4KB gzipped.

Every AI chat app using react-markdown re-parses the entire conversation on every token. That's O(n²). Flowdown processes each token exactly once. That's O(n).

Performance

Benchmark	Flowdown	marked	markdown-it
Streaming (2K tokens)	7.8ms	16,765ms	—
DOM output (9KB)	7.3ms	13.4ms	12.9ms
String output (9KB)	0.77ms	1.00ms	0.87ms
Bundle (gzipped)	~4KB	12KB	51KB

Flowdown is 2,146x faster than marked for streaming the same document.

Install

npm install @a5omic/flowdown

Usage

import { Flowdown } from '@a5omic/flowdown';

const renderer = new Flowdown({
  container: document.getElementById('output'),
});

// Stream tokens as they arrive from the LLM
for await (const chunk of stream) {
  renderer.push(chunk);
}
renderer.end();

React

npm install @a5omic/flowdown @a5omic/flowdown-react

import { StreamMarkdown } from '@a5omic/flowdown-react';

function ChatMessage({ content }: { content: string }) {
  return <StreamMarkdown content={content} />;
}

Static Rendering

const html = Flowdown.renderToString('# Hello **world**');
// → '<h1>Hello <strong>world</strong></h1>'

With Syntax Highlighting

import { Flowdown } from '@a5omic/flowdown';
import hljs from 'highlight.js';

const renderer = new Flowdown({
  container: document.getElementById('output'),
  highlight: (code, lang) => {
    if (lang && hljs.getLanguage(lang)) {
      return hljs.highlight(code, { language: lang }).value;
    }
    return code;
  },
});

Viewport Virtualization

For long LLM responses, enable virtualization to keep DOM node count flat:

const renderer = new Flowdown({
  container: document.getElementById('output'),
  virtualize: true,
  overscan: 2,
});

Off-screen blocks are replaced with height-matched spacers. Scrolling back materializes them from cache.

How It Works

Traditional markdown renderers parse the entire input into an AST, then render the full AST to DOM on every update. During LLM streaming, this means O(n²) total work.

Flowdown uses an incremental state machine parser that:

1. Only processes new characters (never re-parses old content)
2. Emits minimal DOM operations directly (no intermediate AST)
3. Batches DOM writes per animation frame
4. Handles incomplete markdown gracefully (FOIM prevention)
5. Virtualizes off-screen blocks to keep DOM node count constant

Read RESEARCH.md for the full technical deep dive.

API

new Flowdown(options)

Option	Type	Default	Description
container	HTMLElement	required	DOM element to render into
highlight	(code, lang) => string | Promise<string>	—	Syntax highlighter for completed code blocks
onCodeBlock	(code, lang) => void	—	Callback when a code block completes
sanitize	boolean	true	Sanitize URLs (XSS prevention)
virtualize	boolean	false	Enable viewport virtualization
overscan	number	2	Blocks to keep rendered outside viewport

Instance Methods

• push(chunk) — Process a chunk of streaming markdown
• flush() — Materialize the unfinished trailing line without ending the stream
• end() — Signal end of stream, flush buffered content
• reset() — Clear all state and output, ready for reuse
• destroy() — Clean up all resources
• getViewportStats() — Returns { total, visible, virtualized } block counts

Static Methods

• Flowdown.renderToString(markdown) — Parse markdown to HTML string (no DOM required)

Supported Markdown

Flowdown targets "LLM markdown" — the subset that AI models actually output:

• Headings (# ## ### ####)
• Bold, italic, strikethrough, inline code
• Fenced code blocks with language hints
• Links and images (inline syntax)
• Unordered and ordered lists
• Blockquotes (including nested code blocks)
• GFM pipe tables with column alignment
• Horizontal rules

Intentionally not supported (not used by LLMs): reference links, setext headings, indented code blocks, HTML blocks.

License

MIT