@opticlm/streamup

A simple, headless React streaming markdown renderer.

Install

pnpm add @opticlm/streamup react react-dom

Usage

import { Streamup } from '@opticlm/streamup'

// Basic
<Streamup>{'# Hello **world**'}</Streamup>

// Streaming (incomplete markdown)
<Streamup streaming>{'**bold text without clos'}</Streamup>

// Custom components
<Streamup
  components={{
    h1: ({ children }) => <h1 className="text-4xl font-bold">{children}</h1>,
    p: ({ children }) => <p className="my-4 leading-relaxed">{children}</p>,
    code: ({ children, className, ...props }) => {
      const isBlock = 'data-block' in props
      if (isBlock) {
        return <pre className="bg-zinc-900 p-4 rounded"><code>{children}</code></pre>
      }
      return <code className="bg-zinc-100 px-1 rounded">{children}</code>
    },
  }}
>
  {markdown}
</Streamup>

What's included by default

All parsing is always enabled:

• GFM: tables, strikethrough, task lists, autolinks
• Math: block equtions
• CJK: proper emphasis, strikethrough, and autolink handling for Chinese/Japanese/Korean text
• HTML: raw HTML with sanitization
• Footnotes: reference and definition syntax

KaTeX rendering

Math syntax is always parsed. To render it with KaTeX, add the plugin:

pnpm add katex rehype-katex

import { Streamup } from '@opticlm/streamup'
import { katex } from '@opticlm/streamup/katex'
import 'katex/dist/katex.min.css'

// Default options
<Streamup plugins={[katex()]}>{'$$E = mc^2$$'}</Streamup>

// Custom KaTeX options
<Streamup plugins={[katex({ errorColor: '#ff0000', strict: false })]}>
  {'$$E = mc^2$$'}
</Streamup>

Mermaid diagrams

pnpm add mermaid

import { Streamup } from '@opticlm/streamup'
import { withMermaid } from '@opticlm/streamup/mermaid'

// Default
<Streamup components={withMermaid()}>
  {'```mermaid\ngraph TD\n  A-->B\n```'}
</Streamup>

// With mermaid config (theme, flowchart direction, etc.)
<Streamup components={withMermaid({ config: { theme: 'dark' } })}>
  {'```mermaid\ngraph TD\n  A-->B\n```'}
</Streamup>

// With custom fallback code component
<Streamup components={withMermaid({
  config: { theme: 'forest' },
  fallbackCode: MyCodeBlock,
})}>
  {markdown}
</Streamup>

Or use the renderer directly:

import { MermaidRenderer } from '@opticlm/streamup/mermaid'

<MermaidRenderer code="graph TD; A-->B" config={{ theme: 'dark' }} />

Configuration

Single-dollar math

By default, only $$...$$ block math is enabled. Enable $...$ inline math:

<Streamup singleDollarTextMath>{markdown}</Streamup>

URL transform

Transform or remove URLs before rendering:

<Streamup urlTransform={(url) => url.replace('http:', 'https:')}>
  {markdown}
</Streamup>

// Remove all links
<Streamup urlTransform={() => null}>{markdown}</Streamup>

Element filtering

Filter which elements are allowed to render. Returning false removes the element but keeps its children:

<Streamup allowElement={(el) => el.tagName !== 'img'}>
  {markdown}
</Streamup>

Custom sanitization

Replace the default sanitization schema. Spread defaultSanitizeSchema to extend it:

import { Streamup, defaultSanitizeSchema } from '@opticlm/streamup'

<Streamup sanitizeSchema={{
  ...defaultSanitizeSchema,
  attributes: {
    ...defaultSanitizeSchema.attributes,
    div: ['className', 'style'],
  },
}}>
  {markdown}
</Streamup>

Custom remark/rehype plugins

Add custom remark or rehype plugins via the plugin system:

import type { StreamupPlugin } from '@opticlm/streamup'
import myRemarkPlugin from 'remark-my-plugin'
import myRehypePlugin from 'rehype-my-plugin'

const myPlugin: StreamupPlugin = {
  remarkPlugins: [myRemarkPlugin],
  rehypePlugins: [[myRehypePlugin, { option: true }]],
}

<Streamup plugins={[myPlugin]}>{markdown}</Streamup>

Utilities

import { remend, parseMarkdownIntoBlocks, processMarkdown } from '@opticlm/streamup'

// Heal incomplete markdown (streaming)
remend('**bold')        // '**bold**'
remend('~~strike')      // '~~strike~~'
remend('[link](http')   // '[link](streamup:incomplete-link)'

// Split markdown into blocks for incremental rendering
parseMarkdownIntoBlocks('# Title\n\nParagraph')
// ['# Title\n\n', 'Paragraph\n']

// Low-level: process markdown to React elements
processMarkdown('# Hello', {
  components: myComponents,
  processorOptions: { singleDollarTextMath: true },
  urlTransform: (url) => url,
})

Props

Prop	Type	Default	Description
children	string	''	Markdown content
streaming	boolean	false	Heal incomplete markdown before rendering
components	Partial<Components>	unstyled HTML	Override rendering for any element
plugins	StreamupPlugin[]	[]	Add remark/rehype plugins (e.g. katex())
className	string	—	Class on the wrapper <div>
singleDollarTextMath	boolean	false	Enable $...$ inline math syntax
sanitizeSchema	SanitizeSchema	built-in	Custom HTML sanitization schema
urlTransform	UrlTransform	—	Transform or remove URLs
allowElement	AllowElement	—	Filter elements (return false to remove)

Styling GFM task lists

GFM task lists are rendered with class names from remark-gfm:

• ul.contains-task-list — the list container
• li.task-list-item — each task item (contains an <input type="checkbox" disabled>)

ul.contains-task-list {
  list-style: none;
  padding-left: 0;
}

li.task-list-item {
  display: flex;
  align-items: baseline;
  gap: 0.5em;
}

Components you can override

Every HTML element can be overridden. Each component receives its standard HTML props plus node (the HAST element).

Common overrides: h1–h6, p, a, img, code, pre, blockquote, table, thead, tbody, tr, th, td, ol, ul, li, hr, strong, em, del, sup, sub.

License

MIT