| title | @streamdown/math | |
|---|---|---|
| description | Render mathematical expressions using KaTeX. | |
| type | reference | |
| summary | KaTeX-powered LaTeX rendering for inline and block math expressions. | |
| prerequisites |
|
|
| related |
|
The @streamdown/math plugin renders mathematical expressions using KaTeX.
- Fast LaTeX rendering (2-3x faster than MathJax)
- Inline and block math support
- MathML output for accessibility
- Configurable error color and single-dollar syntax
npm install @streamdown/math
If you use Tailwind v4, add this to your globals.css only when @streamdown/math is installed:
@source "../node_modules/@streamdown/math/dist/*.js";Adjust the path for monorepos so it points to the correct node_modules location.
import { math } from '@streamdown/math';
import 'katex/dist/katex.min.css';
<Streamdown plugins={{ math }}>
{markdown}
</Streamdown>Streamdown uses double dollar signs ($$) to delimit mathematical expressions. Unlike traditional LaTeX, single dollar signs ($) are not used by default to avoid conflicts with currency symbols in regular text.
Wrap inline mathematical expressions with $$:
The quadratic formula is $$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$ for solving equations.Renders as: The quadratic formula is
For display-style equations, place $$ delimiters on separate lines:
$$
E = mc^2
$$This renders the equation centered and larger:
$$\frac{numerator}{denominator}$$Example:
$$\sqrt{x}$$ or $$\sqrt[n]{x}$$Example:
$$x^2$$ or $$x_i$$ or $$x_i^2$$Example:
$$\alpha, \beta, \gamma, \delta, \theta, \pi, \sigma, \omega$$
$$\Gamma, \Delta, \Theta, \Pi, \Sigma, \Omega$$Common letters:
$$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$The sum of first
$$\int_{a}^{b} f(x) \, dx$$Definite integral:
$$\lim_{x \to \infty} \frac{1}{x} = 0$$Example:
$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
$$A 2×2 matrix:
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$$$
e^{i\pi} + 1 = 0
$$$$
f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2}
$$The probability density function:
$$
e^x = \sum_{n=0}^{\infty} \frac{x^n}{n!} = 1 + x + \frac{x^2}{2!} + \frac{x^3}{3!} + \cdots
$$$$
\int u \, dv = uv - \int v \, du
$$$$\leq$$ $$\geq$$ $$\neq$$ $$\approx$$ $$\equiv$$$$\in$$ $$\notin$$ $$\subset$$ $$\subseteq$$ $$\cup$$ $$\cap$$ $$\emptyset$$$$\land$$ $$\lor$$ $$\neg$$ $$\implies$$ $$\iff$$ $$\forall$$ $$\exists$$$$\frac{dy}{dx}$$ $$\frac{\partial f}{\partial x}$$ $$\nabla$$ $$\infty$$Derivative:
Customize how errors are displayed using createMathPlugin:
import { Streamdown } from 'streamdown';
import { createMathPlugin } from '@streamdown/math';
import 'katex/dist/katex.min.css';
const math = createMathPlugin({
errorColor: '#dc2626',
});
export default function Page() {
return (
<Streamdown plugins={{ math }}>
{markdown}
</Streamdown>
);
}import { Streamdown } from 'streamdown';
import { createMathPlugin } from '@streamdown/math';
import 'katex/dist/katex.min.css';
const math = createMathPlugin({
singleDollarTextMath: true, // Enable $...$ syntax (default: false)
errorColor: '#dc2626', // Custom error color (default: "var(--color-muted-foreground)")
});
export default function Page() {
return (
<Streamdown plugins={{ math }}>
{markdown}
</Streamdown>
);
}Use getStyles() to get the CSS path programmatically:
import { math } from '@streamdown/math';
const cssPath = math.getStyles?.();
// "katex/dist/katex.min.css"Streamdown's unterminated block parser handles incomplete equations gracefully:
$$
E = mc^During streaming, the parser detects the incomplete block-level equation and adds the closing $$ delimiter, ensuring proper rendering even before the equation is complete.
The parser distinguishes between inline and block math:
-
Inline:
$$E = mc^2$$ (same line) - Block: Separate lines with newlines
This is inline $$E = mc^2$$ math.
$$
E = mc^2
$$
This is block math.In JavaScript/TypeScript strings, backslashes need to be escaped:
// ❌ Wrong
const markdown = "$\frac{1}{2}$";
// ✅ Correct
const markdown = "$$\\frac{1}{2}$$";
// ✅ Or use template literals
const markdown = `$$\frac{1}{2}$$`;Streamdown uses $$ for math to avoid conflicts with currency:
This item costs $5 and that one costs $10. (These are currency symbols)
This equation $$x = 5$$ is mathematical notation. (This is math)Use \, for thin space, \: for medium space, \; for thick space:
$$\int f(x) \, dx$$Better spacing:
Mathematical expressions rendered by KaTeX include:
- MathML - Machine-readable math representation
- Title Attributes - LaTeX source in tooltips
- Semantic HTML - Proper structure for screen readers
- Scalable Typography - Math scales with text size settings
The Math plugin implements the MathPlugin interface:
interface MathPlugin {
name: "katex";
type: "math";
remarkPlugin: Pluggable; // remark-math for parsing
rehypePlugin: Pluggable; // rehype-katex for rendering
getStyles?: () => string; // Returns "katex/dist/katex.min.css"
}Break complex equations into steps:
Start with the equation:
$$
f(x) = ax^2 + bx + c
$$
Complete the square:
$$
f(x) = a\left(x + \frac{b}{2a}\right)^2 + c - \frac{b^2}{4a}
$$Explain your equations:
The Pythagorean theorem states that for a right triangle:
$$
a^2 + b^2 = c^2
$$
where $$a$$ and $$b$$ are the legs and $$c$$ is the hypotenuse.Reserve inline math for simple expressions:
✅ Good: The slope is $$m = \frac{y_2 - y_1}{x_2 - x_1}$$
❌ Avoid: $$\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}$$ in the middle of text
✅ Better:
$$
\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
$$- KaTeX Documentation - Complete list of supported functions
- KaTeX Support Table - Feature compatibility
- LaTeX Math Symbols - Symbol reference
- Typography - Text styling that complements mathematical content
- Unterminated Block Parsing - How streaming works with equations
- GitHub Flavored Markdown - Extended Markdown features