{"record":{"id":"43646bf4d1e8d7ed","repo":"slab/quill","slug":"formula-module-requires-katex","errorCode":null,"errorMessage":"Formula module requires KaTeX.","messagePattern":"Formula module requires KaTeX\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/quill/src/formats/formula.ts","lineNumber":11,"sourceCode":"import Embed from '../blots/embed.js';\n\nclass Formula extends Embed {\n  static blotName = 'formula';\n  static className = 'ql-formula';\n  static tagName = 'SPAN';\n\n  static create(value: string) {\n    // @ts-expect-error\n    if (window.katex == null) {\n      throw new Error('Formula module requires KaTeX.');\n    }\n    const node = super.create(value) as Element;\n    if (typeof value === 'string') {\n      // @ts-expect-error\n      window.katex.render(value, node, {\n        throwOnError: false,\n        errorColor: '#f00',\n      });\n      node.setAttribute('data-value', value);\n    }\n    return node;\n  }\n\n  static value(domNode: Element) {\n    return domNode.getAttribute('data-value');\n  }\n\n  html() {","sourceCodeStart":1,"sourceCodeEnd":29,"githubUrl":"https://github.com/slab/quill/blob/539cbffd0a13b18e9c65eb84dd35e6596e403158/packages/quill/src/formats/formula.ts#L1-L29","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Include KaTeX globally before any formula use: add the KaTeX CSS and JS (window.katex) to the page.","In a bundler, import and expose it: import katex from 'katex'; (window as any).katex = katex;.","If you do not need formulas, remove 'formula' from the toolbar config and from the formats option so the blot is never instantiated.","Load KaTeX synchronously (or await its loader) before enabling the formula toolbar entry."],"exampleFix":"// before - inserting a formula with no KaTeX on the page\nquill.insertEmbed(0, 'formula', 'e=mc^2'); // throws: Formula module requires KaTeX\n\n// after - expose katex globally before use\nimport katex from 'katex';\n(window as any).katex = katex;\nquill.insertEmbed(0, 'formula', 'e=mc^2');\n\n// or remove the formula toolbar button and omit 'formula' from formats if unused","handlingStrategy":"type-guard","validationCode":"// Check KaTeX is available before inserting a formula\nfunction assertKatexAvailable() {\n  if (typeof window === 'undefined' || window.katex == null) {\n    throw new Error(\n      'Cannot insert formula: KaTeX is not loaded. Add the KaTeX script or import katex and assign window.katex.',\n    );\n  }\n}\n\n// usage\nassertKatexAvailable();\nquill.insertEmbed(index, 'formula', latex);","typeGuard":"function hasKatex() {\n  return typeof window !== 'undefined' && typeof window.katex?.render === 'function';\n}\n\n// usage\nif (hasKatex()) {\n  quill.insertEmbed(index, 'formula', latex);\n} else {\n  // disable the formula toolbar button or surface a user-facing message\n}","tryCatchPattern":"try {\n  quill.insertEmbed(index, 'formula', latex);\n} catch (err) {\n  if (String(err?.message).includes('KaTeX')) {\n    // KaTeX not loaded - skip the embed and notify the user\n    console.warn('Formula not inserted: KaTeX is missing.');\n    return;\n  }\n  throw err;\n}","preventionTips":["Load KaTeX (CSS + JS, exposing window.katex) synchronously before enabling the formula toolbar button.","Gate the formula toolbar entry behind a hasKatex() check so users cannot trigger it without the dependency.","In bundler setups, import katex and assign it to window explicitly at app entry.","Omit 'formula' from the formats option when math support is not required."],"tags":["katex","formula","external-dependency","formats","window-global"],"backgroundTag":null,"analyzedSha":"539cbffd0a13b18e9c65eb84dd35e6596e403158","analyzedAt":"2026-08-12T17:15:45.919Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}