slab/quill · error · Error

Formula module requires KaTeX.

Error message

Formula module requires KaTeX.

What it means

The Formula format (packages/quill/src/formats/formula.ts:3) renders LaTeX by calling window.katex.render inside Formula.create. It throws when window.katex is null/undefined because there is no renderer to produce the math markup. This is a format/blot, so the throw fires when a formula embed is created or inserted, not at Quill construction time.

Source

Thrown at packages/quill/src/formats/formula.ts:11

import Embed from '../blots/embed.js';

class Formula extends Embed {
  static blotName = 'formula';
  static className = 'ql-formula';
  static tagName = 'SPAN';

  static create(value: string) {
    // @ts-expect-error
    if (window.katex == null) {
      throw new Error('Formula module requires KaTeX.');
    }
    const node = super.create(value) as Element;
    if (typeof value === 'string') {
      // @ts-expect-error
      window.katex.render(value, node, {
        throwOnError: false,
        errorColor: '#f00',
      });
      node.setAttribute('data-value', value);
    }
    return node;
  }

  static value(domNode: Element) {
    return domNode.getAttribute('data-value');
  }

  html() {

View on GitHub (pinned to 539cbffd0a)

Solutions

1. Include KaTeX globally before any formula use: add the KaTeX CSS and JS (window.katex) to the page.
2. In a bundler, import and expose it: import katex from 'katex'; (window as any).katex = katex;.
3. If you do not need formulas, remove 'formula' from the toolbar config and from the formats option so the blot is never instantiated.
4. Load KaTeX synchronously (or await its loader) before enabling the formula toolbar entry.

Example fix

// before - inserting a formula with no KaTeX on the page
quill.insertEmbed(0, 'formula', 'e=mc^2'); // throws: Formula module requires KaTeX

// after - expose katex globally before use
import katex from 'katex';
(window as any).katex = katex;
quill.insertEmbed(0, 'formula', 'e=mc^2');

// or remove the formula toolbar button and omit 'formula' from formats if unused

// Check KaTeX is available before inserting a formula
function assertKatexAvailable() {
  if (typeof window === 'undefined' || window.katex == null) {
    throw new Error(
      'Cannot insert formula: KaTeX is not loaded. Add the KaTeX script or import katex and assign window.katex.',
    );
  }
}

// usage
assertKatexAvailable();
quill.insertEmbed(index, 'formula', latex);

function hasKatex() {
  return typeof window !== 'undefined' && typeof window.katex?.render === 'function';
}

// usage
if (hasKatex()) {
  quill.insertEmbed(index, 'formula', latex);
} else {
  // disable the formula toolbar button or surface a user-facing message
}

try {
  quill.insertEmbed(index, 'formula', latex);
} catch (err) {
  if (String(err?.message).includes('KaTeX')) {
    // KaTeX not loaded - skip the embed and notify the user
    console.warn('Formula not inserted: KaTeX is missing.');
    return;
  }
  throw err;
}

When it happens

Trigger: Clicking the toolbar formula button or calling quill.insertEmbed(index, 'formula', latex) while window.katex is undefined; loading KaTeX asynchronously and inserting a formula before it resolves; bundler setup that imports katex as a module but never assigns it to window; SSR where window.katex is absent.

Common situations: Forgot to include the KaTeX <script> tag; KaTeX CSS/JS loaded after the Quill interaction; using a bundler that does not expose katex as a global; removing KaTeX to slim the bundle but leaving the formula toolbar button enabled.

Related errors

• Syntax module requires highlight.js. Please include the libr

AI-assisted analysis of slab/quill@539cbffd0a (2026-08-12). Data as JSON: /api/errors/43646bf4d1e8d7ed. Report an issue: GitHub.