Vue KaTeX Plugin

Common errors

• KaTeX parse error: Undefined control sequence: \frac at position 1

  cause Incorrect TeX syntax or unescaped backslashes in a template string.
  fix Double-check your TeX expression for syntax errors and ensure all backslashes are escaped (e.g., `v-katex="'\\frac{a}{b}'"`).

• Failed to resolve component: katex-element

  cause The `vue-katex` plugin (which registers `KatexElement` and `v-katex`) has not been registered with Vue.
  fix Ensure you have called `Vue.use(VueKatex)` in your application's entry point after importing `Vue` and `VueKatex`.

• Math expressions appear unstyled, in plain text, or with incorrect fonts.

  cause KaTeX stylesheet `katex.min.css` is not loaded in your application.
  fix Import `katex/dist/katex.min.css` in your main JavaScript file or include it via a `<link>` tag in your `index.html`.

Warnings

• gotcha Ensure KaTeX peer dependency matches `vue-katex` version support. `vue-katex@0.5.0` is specifically designed for KaTeX `0.12.0`.
  Fix: Check `vue-katex` releases for specific KaTeX version compatibility and install the appropriate `katex` version (e.g., `npm i katex@^0.12.0`).
• gotcha KaTeX's essential stylesheet (`katex.min.css`) is not automatically bundled or injected by `vue-katex`. Failure to import it will result in unstyled or incorrectly rendered math expressions.
  Fix: Explicitly import the stylesheet in your entry point: `import 'katex/dist/katex.min.css';` or include it via an HTML `<link>` tag.
• gotcha When using the `v-katex` directive with string literals in Vue templates, remember to escape all backslashes (`\`) in your TeX expressions, as single backslashes are interpreted as JavaScript escape sequences.
  Fix: Use double backslashes for all TeX commands (e.g., `'\\frac{a_i}{1+x}'` instead of `'\frac{a_i}{1+x}'`).
• gotcha Local KaTeX options provided to `v-katex` or `KatexElement` will override globally defined options, except for `object` or `array` type options, which are merged.
  Fix: Be aware of the merging behavior when defining global and local options. For full control, provide complete option objects locally or manage global options carefully.

Install

• npm install vue-katex npm
• yarn add vue-katex yarn
• pnpm add vue-katex pnpm

Imports

• Vue
  wrong:

  const Vue = require('vue')

  correct:

  import Vue from 'vue'

  Essential peer dependency for initializing the Vue plugin.
• VueKatex
  wrong:

  import { VueKatex } from 'vue-katex'

  correct:

  import VueKatex from 'vue-katex'

  The main plugin is a default export and is registered with `Vue.use()`.
• katex.min.css
  wrong:

  require('katex/dist/katex.min.css')

  correct:

  import 'katex/dist/katex.min.css'

  Crucial stylesheet for correct KaTeX rendering; must be imported separately.

Quickstart

This quickstart demonstrates the setup of `vue-katex` by registering it globally with `Vue.use()`, including the necessary stylesheet. It then showcases both the `v-katex` directive for rendering inline and display math with options, including `auto-render` functionality, and the `<katex-element>` component for declarative TeX expression rendering.

import Vue from 'vue';
import VueKatex from 'vue-katex';
import 'katex/dist/katex.min.css';

Vue.use(VueKatex, {
  globalOptions: {
    displayMode: true, // Default to display mode globally
    throwOnError: false,
    errorColor: '#FF0000'
  }
});

new Vue({
  el: '#app',
  data: {
    inlineMath: '\\frac{a_i}{1+x^2}',
    displayMath: '\\int_0^1 x^2 dx = \\frac{1}{3}',
    autoRenderContent: 'The quadratic formula is \\(x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}\\)
 and then some display math: $$ E=mc^2 $$'
  },
  template: `
    <div id="app">
      <h1>Vue KaTeX Example</h1>

      <h2>Using v-katex directive</h2>
      <p>Inline: <span v-katex="inlineMath"></span></p>
      <p>Display mode (local override): <div v-katex:display="displayMath"></div></p>
      <p>With options: <div v-katex="{ expression: '\\sqrt{2}', options: { throwOnError: false, errorColor: '#00F' } }"></div></p>

      <h2>Using v-katex:auto directive</h2>
      <div v-katex:auto>
        {{ autoRenderContent }}
      </div>

      <h2>Using KatexElement component</h2>
      <katex-element :expression="displayMath" :display-mode="false" />
      <katex-element expression="\\sum_{n=1}^\\infty \\frac{1}{n^2} = \\frac{\\pi^2}{6}" :display-mode="true" :throw-on-error="false" error-color="#00A" />

      <p>Check the console for any KaTeX errors if throwOnError is false.</p>
    </div>
  `
});