Math

Render math expressions that don't require a full TeX distribution at build-time with MathJax or KaTeX.

• Automatic CSS: MathJax and KaTeX need CSS to work properly. SvelTeX will by default automatically take care of this for you.

• Adaptive theming: MathJax and KaTeX both use currentColor for their output by default. KaTeX also natively supports CSS color variables, and for MathJax this behavior is emulated by SvelTeX.

• Accessible by default: Both backends emit assistive MathML alongside their visual output by default, so screen readers can announce your math.

• Custom transformers: Inject custom transformers to pre- and post-process the in- and output of the math renderer, respectively.

Backends

The following backends are supported for math rendering:

• MathJax [web / github / npm]: An extensible math renderer that supports many TeX and LaTeX commands and places a lot of focus on accessibility. It supports SVG and CHTML output. It's somewhat bulkier and slower than KaTeX, but this matters primarily for client-side rendering, which is non-existent with SvelTeX — instead, in this context the only effect that the difference in performance might have is potentially yielding marginally slower build times.

  Using the mathjax backend requires the @mathjax/src package (version 4 or later), as well as the font package matching your math.font setting. See Installation below.

• KaTeX [web / github / npm]: A fast math renderer that supports many TeX and LaTeX commands and produces CHTML output. It supports fewer commands than MathJax, and only a few extensions.

Installation

The math backend's renderer isn't bundled with SvelTeX — you install whichever one you've chosen as a peer dependency.

For KaTeX, install katex:

pnpm

pnpm add -D katex

bun

bun add -D katex

npm

npm add -D katex

yarn

yarn add -D katex

For MathJax, install @mathjax/src (version 4 or later). MathJax v4 also ships each math font as a separate npm package, so you additionally need the @mathjax/mathjax-<font>-font package that matches your math.font setting. With the default font (newcm), that's @mathjax/mathjax-newcm-font:

pnpm

pnpm add -D @mathjax/src @mathjax/mathjax-newcm-font

bun

bun add -D @mathjax/src @mathjax/mathjax-newcm-font

npm

npm add -D @mathjax/src @mathjax/mathjax-newcm-font

yarn

yarn add -D @mathjax/src @mathjax/mathjax-newcm-font

Info

SvelTeX used mathjax-full (MathJax v3) before v0.5.0. As of v0.5.0, the mathjax backend targets the @mathjax/src package at version 4 or later instead. If you're upgrading, replace mathjax-full with @mathjax/src and add the font package for your chosen math.font.

Configuration

For every available option and its type, see the MathConfiguration API reference.

Hint: Hover over the different properties in the code block to show some IntelliSense.

MathJax

// sveltex.config.js
import { sveltex } from '@nvl/sveltex'

export default await sveltex({
    mathBackend: 'mathjax',
}, {
    math: {
        css: {
            type: 'hybrid',
            // Either a single CDN name, or an ordered fallback list. The
            // default is to try them in this order, picking the first one
            // that's reachable at build time.
            cdn: ['jsdelivr', 'esm.sh', 'cdnjs', 'unpkg'],
        },
        mathjax: {
            // Options passed to MathJax; note that some of the
            // options may be ineffective, since SvelTeX takes
            // care of some of the functionality that MathJax
            // usually provides (e.g., finding math within a
            // source file).
        },
        // 'svg' or 'chtml' (default). See "Output format" below.
        outputFormat: 'svg',
        transformers: {
            pre: [],
            post: [],
        },
    }
})

KaTeX

// sveltex.config.js
import { sveltex } from '@nvl/sveltex'

export default await sveltex({
    mathBackend: 'katex',
}, {
    math: {
        css: {
            type: 'cdn',
            cdn: 'jsdelivr'
        },
        katex: {
            // Options passed to KaTeX
        },
        transformers: {
            pre: [],
            post: [],
        },
    }
})

Output format mathjax

The mathjax backend can render math either as CHTML (CommonHTML, the default) or as SVG. Pick one with the math.outputFormat setting:

// sveltex.config.js
import { sveltex } from '@nvl/sveltex'

export default await sveltex({
    mathBackend: 'mathjax',
}, {
    math: {
        outputFormat: 'svg', // or 'chtml' (default)
    }
})

MathJax v4 initializes a single, process-global document, so each build uses one output format throughout — you can't mix svg and chtml within the same build. This is fine for any SvelteKit build, since a project picks one format for all of its pages anyway.

Warning

You'll have to delete the previously generated MathJax CSS file if you change the output format, otherwise the change won't take effect.

Fonts mathjax

MathJax v4 ships each of its math fonts as a separate npm package. SvelTeX defaults to New Computer Modern (@mathjax/mathjax-newcm-font); set math.font to use a different one. Whichever font you pick, remember to install the matching @mathjax/mathjax-<font>-font package (see Installation).

// sveltex.config.js
import { sveltex } from '@nvl/sveltex'

export default await sveltex({
    mathBackend: 'mathjax',
}, {
    math: {
        font: 'newcm', // the default
    }
})

The supported fonts are newcm, asana, bonum, dejavu, fira, modern, pagella, schola, stix2, termes, and tex; each corresponds to a @mathjax/mathjax-<font>-font package.

Warning

You'll have to delete the previously generated MathJax CSS file if you change the font, otherwise the change won't take effect.

Accessibility

SvelTeX renders accessible math out of the box.

• KaTeX emits MathML alongside its visual HTML output by default (i.e., SvelTeX sets KaTeX's output option to 'htmlAndMathml'). Screen readers use the MathML; sighted users see the HTML.

• MathJax emits assistive MathML by default, and leaves MathJax's own speech-string generation off. Emitting both an assistive-MathML tree and speech strings can cause some screen readers to announce an expression twice, so SvelTeX enables just the MathML by default.

MathJax accessibility options mathjax

For the mathjax backend, the relevant accessibility settings live under math.mathjax.options. SvelTeX treats the following enable* options as meta-options: each one decides whether SvelTeX loads the corresponding MathJax accessibility component, so turning a feature on or off behaves as documented.

Option	Default	Effect
enableAssistiveMml	true	Insert an assistive MathML tree next to each expression.
enableEnrichment	false	Apply semantic enrichment to the internal MathML.
enableSpeech	false	Generate and attach speech strings.
enableBraille	false	Generate and attach Braille labels.
enableComplexity	false	Run the complexity extension's build-time computations.

Turning on enableSpeech, enableBraille, or enableComplexity implies semantic enrichment, since those components need it — so enrichment runs even when enableEnrichment is left at false.

// sveltex.config.js
import { sveltex } from '@nvl/sveltex'

export default await sveltex({
    mathBackend: 'mathjax',
}, {
    math: {
        mathjax: {
            options: {
                enableAssistiveMml: true,
                enableSpeech: false,
            },
        },
    }
})

Info

SvelTeX is purely a build-time preprocessor, so MathJax accessibility features that require running MathJax in the browser — the contextual menu, the explorer extension, and the collapsing behavior of the complexity extension — are not supported. This is why SvelTeX turns assistive MathML on by default: in MathJax v4 it's off by default, on the assumption that the in-browser menu and explorer are available.