How to use KaTeX: load it, render math and avoid common pitfalls

What KaTeX does and who it suits

KaTeX renders math synchronously and, according to its README, doesn't need to reflow the page. Its layout is based on Donald Knuth's TeX, and it has no dependencies, so it can be bundled with your website resources. It is compatible with Chrome, Safari, Firefox, Opera and Edge.

• Good fit: readable equations in articles, docs or course pages
• Good fit: a lightweight renderer inside a web app
• Good fit: servers that pre-render math and send plain HTML
• Poor fit: full LaTeX support, since KaTeX supports much but not all of LaTeX and many packages
• Poor fit: rendering non-math documents or typesetting whole pages

Add KaTeX to a web page with the starter template

The simplest route is to load KaTeX from the jsDelivr CDN by copying the link tags from the starter template in the README. The template includes the stylesheet, the deferred KaTeX script and the auto-render extension. Keep the HTML5 doctype, because the README notes that without it KaTeX may not render properly.

You can also download KaTeX from its releases page and host the files yourself. Either way, the CSS and font files must be included for rendering to work.

• Use the HTML5 doctype at the top of the page
• Include the stylesheet katex.min.css in the head
• Load katex.min.js and, for automatic rendering, contrib/auto-render.min.js
• The auto-render script calls renderMathInElement(document.body) on load

Render math with katex.render in the browser

Call katex.render to draw a TeX expression directly into a DOM element. Pass the expression, the target element and an options object. The README example uses throwOnError set to false, which shows invalid input as the TeX source in red with the error message as hover text.

The expression is a JavaScript string, so backslashes must be escaped as double backslashes.

• First argument: the TeX expression as a string
• Second argument: the element to render into
• Third argument: options, such as throwOnError

Pre-render math on the server with renderToString

Call katex.renderToString to produce an HTML string instead of writing to the page. This suits server-side rendering: the README says KaTeX gives the same output regardless of browser or environment, so you can pre-render with Node.js and send plain HTML to visitors.

If you render everything on the server, you do not need to include the JavaScript on the client, but the CSS and font files are still required.

• Returns a string such as a span with class katex
• Client does not need katex.min.js when all rendering happens on the server
• CSS and font files are still needed in both approaches

Handle errors and find the full option list

With throwOnError set to false, invalid TeX is displayed as its source rather than stopping the page. The README points to separate documentation for the API, the options and the error handling. Check the list of supported functions before relying on a particular LaTeX command or package.

• API reference: katex.org/docs/api.html
• Options reference: katex.org/docs/options.html
• Error handling: katex.org/docs/error.html
• Auto-render configuration: katex.org/docs/autorender.html
• Supported functions: katex.org/docs/supported.html