Svelte Streamdown

A Svelte port of Streamdown by Vercel - an all in one markdown renderer, designed specifically for AI-powered streaming applications.

📦 Installation

npm install svelte-streamdown# orpnpm add svelte-streamdown# oryarn add svelte-streamdown

🚀 Overview

Perfect for AI-powered applications that need to stream and render markdown content safely and beautifully, with support for incomplete markdown blocks, security hardening, and rich features like code highlighting, math expressions, and interactive diagrams.

✨ Main Features

🔄 Streaming-Optimized

• Incomplete Markdown Parsing: Handles unterminated blocks gracefully
• Progressive Rendering: Perfect for streaming AI responses
• Real-time Updates: Optimized for dynamic content
• Smooth Animations: Animate tokens and blocks as they are streamed.

🔒 Security Hardening

• Image Origin Control: Whitelist allowed image sources
• Link Safety: Control link destinations

🎯 Fully Customizable Components & Theming

• Every component customizable with Svelte snippets
• Granular theming system - customize every part of every component
• Override default styling and behavior for any markdown element
• Full control over rendering with type-safe props
• Seamless integration with your design system

🎨 Built-in Typography Styles

Beautiful, responsive typography with built-in Tailwind CSS classes for headings, lists, code blocks, and more. Comes with a complete default theme that works out of the box.

📝 Extensive Markdown Features

Full support for

• Basic text marks: bold, italic, code, Strikethrough
• _Subscript and ^Superscript
• Links
• Headings (H1–H6)
• Blockquotes
• Github alert
• Ordered & unordered lists (including roman, alpha, nested)
• Task lists ([ ] and [x])
• Code blocks
• Mermaid diagrams
• Math
• Escaping currency symbols ($140)
• Complex tables
• Footnotes 1
• Inline citations streamdown.ai +1
• MDX components (embed custom Svelte components)

💻 Interactive Code Blocks

• Syntax highlighting powered by Shiki
• Copy-to-clipboard functionality
• Support any Shiki themes

🔢 Mathematical Expressions

LaTeX math support through KaTeX:

• Perfect rendering for scientific content
• Inline math:
• Block math:

🧜‍♀️ Mermaid Diagrams

• Render Mermaid diagrams from code blocks
• Incremental rendering during streaming content
• Pan and Zoom
• Full screen mode

Example:

Complex table support

Colspan

Rowspan

Footer

Column alignment

Multiple headers and very complex layout

Complex list support

decimal

1. First item
2. Second item
3. Third item

lower-alpha

1. First item
2. Second item
3. Third item

upper-alpha

1. First item
2. Second item
3. Third item

lower-roman

1. First item
2. Second item
3. Third item

upper-roman

1. First item
2. Second item
3. Third item

Nested Lists

1. First level (numeric)
   1. Second level (lowercase alpha)
   9. Third level (lowercase roman) - Fourth level (bullet)
   1. Fifth level (uppercase roman)
   1. Sixth level (uppercase alpha)
2. Back to the first level

Task List

• Uncompleted task
• Completed task
• Another uncompleted task
  • Nested uncompleted subtask
  • Nested completed subtask

Alert Support

Description List

Topic 1

Description 1

Topic 2

Description 2

Topic 3

Description 3

Topic 3

Description 3

Citation Support

Streamdown supports inline citations that allow you to reference external sources and display them in interactive popovers. Citations work out-of-the-box with a simple object structure and support nested references like this [cloudflare.website, vercel] will render into cloudflare.com +1

To enable inline citations, pass a sources object as a prop to the Streamdown component.

Basic Usage

<script>  import { Streamdown } from 'svelte-streamdown';​  let content = `According to [smith2023], AI is advancing rapidly. See also [nested.subsection] for related work.`;​  let sources = {    "smith2023": {      title: "AI Research Paper",      url: "https://example.com/paper",      content: "Detailed content of the citation..."    },    "nested": {      "subsection": {        title: "Nested Citation",        url: "https://example.com/nested"      }    }  };</script>​<Streamdown {content} {sources} />

Default Citation Structure

Citations work with objects containing these properties:

• title (or name or author): Display title for the citation
• url (or href, url, link or source): Link to the source
• content (or text, summary or excerpt): Rich content to display in carousel mode

Display Modes

Streamdown offers two ways to display citations:

• List View: Shows all citations in a compact list format
• Carousel View (default): Step-through navigation for multiple citations with full content display

You can control the display mode using the inlineCitationsMode prop:

<!-- List view --><Streamdown {content} {sources} inlineCitationsMode="list" />​<!-- Carousel view (default) --><Streamdown {content} {sources} inlineCitationsMode="carousel" />

Citation Popovers

Citations appear as clickable buttons that open popovers when clicked. The popover shows:

• Source title and URL (when available)
• Favicon from the source domain
• Rich content (in carousel mode)
• Navigation controls (in carousel mode for multiple citations)

Custom Citation Rendering

If your citation data structure doesn't match the default format, you can customize how citations are rendered using inlineCitationPreview, inlineCitationContent or inlineCitationPopover snippets:

<Streamdown {content} {sources}>  {#snippet inlineCitationPreview({ token })}    <!-- Customize the clickable citation button -->         {token.keys[0]}  {/snippet}​  {#snippet inlineCitationContent({ source, key, token })}    <!-- Customize content displayed in popover -->    <div class="custom-content">      <h4>{source.customTitle || key}</h4>      <p>{source.customDescription}</p>    </div>  {/snippet}</Streamdown>

These snippets allow you to:

• inlineCitationPreview: Customize the content of the clickable button that appears in the text
• inlineCitationContent: Customize how individual citation content is displayed within popovers
• inlineCitationPopover: Completely customize the list of citations

🔄 Differences from Original React Version

This Svelte port maintains feature parity with the original Streamdown while adapting to Svelte's patterns:

Tailwind CSS Setup

@import 'tailwindcss';/* Add Streamdown styles to your Tailwind build */@source "../node_modules/svelte-streamdown/**/*";

🎭 Animation System

Streamdown includes an animation system designed specifically for streaming AI content, providing smooth and engaging visual feedback as text appears on screen.

How It Works

The animation system works by:

1. Tokenization: Text is broken down into tokens (words or characters) based on your configuration
2. Sequential Animation: Each token animates as it is received
3. Block-level Animation: Entire blocks (paragraphs, headings, code blocks) animate as units

Animation Types

Choose from 4 distinct animation styles:

fade

A clean fade-in effect where text smoothly appears from transparent to opaque.

blur

Text starts slightly blurred and comes into focus while fading in, creating a smooth reveal effect.

slideUp

Text slides up from below while fading in, creating a dynamic upward motion.

slideDown

Text slides down from above while fading in, creating a dynamic downward motion.

🚀 Quick Start

Basic Usage

<script>	import { Streamdown } from 'svelte-streamdown';​	let content = `# Hello World​This is a **bold** text and this is *italic*.​\`\`\`javascriptconsole.log('Hello from Streamdown!');\`\`\``;</script>​<Streamdown {content} />

Advanced Usage with Custom Components

<script>	import { Streamdown } from 'svelte-streamdown';​	let content = `# Custom Components Example​This heading will use a custom component!`;</script>​<Streamdown {content}>	{#snippet heading({ children })}		<h1 class="mb-4 text-4xl font-bold text-blue-600">			{@render children()}		</h1>	{/snippet}</Streamdown>

Security Configuration

<script>	import { Streamdown } from 'svelte-streamdown';​	let markdown = `![Safe Image](https://trusted-domain.com/image.jpg)[Safe Link](https://trusted-domain.com/page)`;</script>​<Streamdown	{content}	allowedImagePrefixes={['https://trusted-domain.com']}	allowedLinkPrefixes={['https://trusted-domain.com']}/>

📋 Props API

All Available Customizable Elements:

Text Elements: heading, p, strong, em, del

Links & Media: a, img

Lists: ul, ol, li

Code: code, codeSpan

Tables: table, thead, tbody, tr, th, td, tfoot

Special Content: blockquote, hr, alert, mermaid, math, footnoteRef, inlineCitation

MDX Components: Any PascalCase component (e.g., Card, Button, MyComponent) - pass as snippets with the component name

Note: The above elements are supported by Streamdown and should be customized using individual props or the theme system.

🎨 Theming System

Built-in Themes

Streamdown comes with two built-in themes:

• Default Theme: The standard theme with gray-based colors
• Shadcn Theme: A theme that uses shadcn/ui design tokens for seamless integration with shadcn-based projects

Beyond custom snippets, Streamdown provides a granular theming system that lets you customize every part of every component without writing custom snippets. You can use the built-in themes (default and shadcn) or create completely custom themes using the mergeTheme utility.

Theme Structure

Every component has multiple themeable parts. For example, the code component has:

code: {  base: 'bg-gray-100 rounded p-2 font-mono text-sm',           // Main code block  container: 'my-4 w-full overflow-hidden rounded-xl border',   // Wrapper container  header: 'flex items-center justify-between bg-gray-100/80',  // Header with language  button: 'cursor-pointer p-1 text-gray-600 transition-all',   // Copy button  language: 'ml-1 font-mono lowercase',                        // Language label  pre: 'overflow-x-auto font-mono p-0 bg-gray-100/40'        // Pre element}

Using Custom Themes

<script>	import { Streamdown } from 'svelte-streamdown';​	let content = `# Custom Theme Example​\`\`\`javascriptconsole.log('Beautiful code blocks!');\`\`\`​> This blockquote is also themed​| Header 1 | Header 2 ||----------|----------|| Cell 1   | Cell 2   |`;​	// Custom theme overrides	let customTheme = {		code: {			container: 'my-6 rounded-2xl border-2 border-purple-200 shadow-lg',			header: 'bg-purple-50 text-purple-700 font-medium',			button: 'text-purple-600 hover:text-purple-800 hover:bg-purple-100'		},		blockquote: {			base: 'border-l-8 border-purple-400 bg-purple-50 p-4 italic text-purple-800'		},		table: {			base: 'border-purple-200 shadow-md',			container: 'my-6 rounded-lg overflow-hidden'		},		th: {			base: 'bg-purple-100 px-6 py-3 text-purple-900 font-bold'		},		td: {			base: 'px-6 py-3 border-purple-100'		}	};</script>​<Streamdown {content} theme={customTheme} />

All Themeable Components

Each component supports multiple themeable parts:

Headings (h1-h6): base

Text Elements (p, strong, em, del): base

Lists (ul, ol, li): base

Links (a): base, blocked (for blocked/unsafe links)

Code (code): base, container, header, button, language, skeleton, pre

Inline Code (inlineCode): base

Images (img): container, base, downloadButton

Tables (table, thead, tbody, tr, th, td): base, container (table only)

Blockquotes (blockquote): base

Alerts (alert): base, title, icon, plus type-specific styles (note, tip, warning, caution, important)

Mermaid (mermaid): base, downloadButton

Math (math, inlineMath): base

Other (hr, sup, sub): base

Theme Merging

Themes are intelligently merged using Tailwind's class merging utility, so you only need to override the specific parts you want to customize while keeping the default styling for everything else.

🧩 MDX Component Support

Streamdown supports MDX-style JSX components, allowing you to embed custom Svelte components directly in your markdown content.

Basic Usage

<script>  import { Streamdown } from 'svelte-streamdown';​  let content = `# Using MDX Components​<Card title="Hello" count={42}>This is **markdown content** inside a component!</Card>​<Button label="Click me" active={true} />`;</script>​<Streamdown {content}>  {#snippet Card({ title, count, children })}    <div class="rounded-lg border border-gray-200 p-4 shadow-sm">      <h3 class="text-xl font-bold">{title}</h3>      <p class="text-gray-600">Count: {count}</p>      <div class="mt-2">        {@render children()}      </div>    </div>  {/snippet}​  {#snippet Button({ label, active })}    <button class="rounded px-4 py-2 {active ? 'bg-blue-500 text-white' : 'bg-gray-200'}">      {label}    </button>  {/snippet}</Streamdown>

Supported Syntax

Self-closing components:

<Component attr="value" count={42} enabled={true} />

Components with markdown children:

<Component title="Hello"># This is a headingThis **markdown** content will be parsed!</Component>

Attribute Types

MDX components support three attribute value types:

• Strings: attr="hello" → "hello"
• Numbers: count={42} or value={3.14} → 42, 3.14
• Booleans: active={true} or disabled={false} → true, false
• Expressions: value={variableName} → "variableName" (stored as string)

Component Naming

• Component names must start with a capital letter (PascalCase)
• Valid: <Card />, <MyComponent />, <Component123 />
• Invalid: <card />, <myComponent /> (these are treated as HTML)

Streaming Safety

MDX components are streaming-safe. Incomplete components are automatically handled during AI streaming:

• Incomplete tags like ``<Component attr are escaped with backticks
• Unclosed components like <Card>content are auto-closed with </Card>
• Malformed attributes are escaped to prevent rendering errors

This ensures your UI remains stable even when receiving partial markdown from streaming AI responses.

Component Props

MDX component snippets receive:

• token: The full MdxToken with tagName, attributes, etc.
• children: Snippet containing parsed markdown content
• All attributes spread directly: Access attributes by name (e.g., title, count, active)

Example:

<!-- Markdown: <Card title="Hello" count={5}>Content</Card> --><Streamdown {content}>  {#snippet Card({ title, count, children })}    <div>      <h3>{title}</h3>      <span>Count: {count}</span>      {@render children()}    </div>  {/snippet}</Streamdown>

💉 Extensibility

Streamdown is extensible through the use of custom extensions.

An extension is an object that has a name, a level and a tokenizer function.

• name: The name of the extension
• level: The level of the extension, can be block or inline
• tokenizer: The tokenizer function, see marked for more information

To render the extension custom tokens, you can then simply use the children snippet.

Example

<script lang="ts">	import { Streamdown, type Extension } from 'svelte-streamdown';	const markedCollapsible: Extension = {		name: 'collapsible',		level: 'block',		tokenizer(this, src) {			// Match [detail]...[detail] blocks (case insensitive)			const detailMatch = src.match(/^\[detail\](.*?)\[detail\]/is);​			if (detailMatch) {				const content = detailMatch[1] || '';				const tokens = this.lexer.blockTokens(content);​				return {					type: 'detail',					raw: detailMatch[0], // The entire matched string including tags					tokens				};			}​			return undefined;		}	};</script>​<Streamdown	extensions={[markedCollapsible]}	content={`[detail]	This is a collapsible **section**[detail]`}>	{#snippet children({ token, streamdown, children })}		{#if token.type === 'detail'}			<details>				<summary> Detail </summary>				<div>					{@render children()}				</div>			</details>		{/if}	{/snippet}</Streamdown>

🛠️ Development

Setup

# Clone the repositorygit clone <repository-url>cd svelte-streamdown​# Install dependenciespnpm install​# Start development serverpnpm dev​# Run testspnpm test​# Build for productionpnpm build

Building

# Build the librarypnpm build​# Preview the showcase apppnpm preview

🤝 Contributing

Contributions are welcome! This is a port of the original Streamdown project, so please:

1. Check the original Streamdown repository for upstream changes
2. Ensure compatibility with the original API
3. Maintain feature parity where possible
4. Add tests for new features if you want

📄 License

MIT

🙏 Acknowledgments

• Original Streamdown: Vercel for creating the original React component
• Svelte Community: For the amazing framework that made this port possible
• All Contributors: For helping improve and maintain this project

Made with ❤️ and 🤖