Render LaTeX in React

Common errors

• LaTeX expressions are not rendering; only showing raw text or unstyled symbols.

  cause The KaTeX CSS file (`katex/dist/katex.min.css`) has not been imported or included in the project's build.
  fix Add `import 'katex/dist/katex.min.css';` to your application's entry point (e.g., `index.js`, `_app.js` in Next.js) or to the component where `Latex` is used.

• Error: KaTeX parse error: LaTeX parse error: Undefined control sequence: \xxx

  cause This error typically occurs when the `strict` prop is enabled on the `Latex` component, and the LaTeX string contains a parsing error (e.g., an undefined command, mismatched delimiters, or invalid syntax).
  fix Either correct the LaTeX syntax within the string, or remove the `strict` prop (it defaults to `false`, which displays the raw text instead of throwing an error).

• Error: Cannot read properties of undefined (reading 'replace') at createHtml

  cause This error can occur if the `Latex` component receives an unexpected child type, such as an array of strings instead of a single string, or `null`/`undefined` children.
  fix Ensure that the `children` prop passed to the `Latex` component is always a single string containing the LaTeX content. Concatenate multiple strings if necessary.

Warnings

• gotcha The KaTeX CSS file (`katex/dist/katex.min.css`) must be explicitly imported or included in your project's bundle for LaTeX expressions to render correctly. Without it, equations may appear unstyled, misaligned, or as raw text.
  Fix: Ensure `import 'katex/dist/katex.min.css';` is present in your entry file or a relevant component. For Next.js, this typically goes into `_app.js` or directly into the component.
• gotcha The `macros` prop allows defining custom KaTeX macros. Be aware that defining macros via `\gdef` can have security implications, as mentioned in the KaTeX documentation. Arbitrary code execution can occur if untrusted input is used in macro definitions.
  Fix: Sanitize any user-provided input before using it to define KaTeX macros via the `macros` prop. Refer to the KaTeX API documentation for detailed security guidance on persistent macros.
• gotcha By default, `react-latex-next` renders in 'non-strict' mode, which means it will fall back to displaying the raw text (without delimiters) if a LaTeX parsing error occurs. If you prefer to throw a JavaScript error instead, you must enable `strict` mode.
  Fix: To enable strict error handling, pass the `strict` prop to the `Latex` component: `<Latex strict>{textWithPotentiallyBrokenLatex}</Latex>`. This will cause rendering to fail and throw an error for invalid LaTeX.
• breaking Major versions of `react-latex-next` may update their peer dependencies on `react` and `react-dom`. Ensure your project's React versions are compatible with the peer dependency ranges specified in `react-latex-next`'s `package.json` to avoid installation warnings or runtime issues.
  Fix: Check the `peerDependencies` in `react-latex-next`'s `package.json` (e.g., `"react": "^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0"`) and upgrade or downgrade your `react` and `react-dom` packages accordingly.
• gotcha Backslashes in LaTeX strings passed as children to the `Latex` component need to be escaped in JavaScript/JSX template literals. For example, `\alpha` should be written as `\\alpha`.
  Fix: When writing LaTeX inside JavaScript strings, especially with template literals, always double-escape backslashes: `$`\\alpha`$`.

Install

• npm install react-latex-next npm
• yarn add react-latex-next yarn
• pnpm add react-latex-next pnpm

Imports

• Latex
  wrong:

  const Latex = require('react-latex-next');

  correct:

  import Latex from 'react-latex-next';

  Primarily designed for ESM imports in modern React applications. CommonJS 'require' may lead to bundler issues or incorrect module resolution in some setups.
• KaTeX CSS

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

  This CSS import is critical for the correct visual rendering of LaTeX. It must be included globally or within a component that is rendered. Without it, only raw text or misformatted equations will appear.
• delimiters (prop)
  wrong:

  <Latex>{`$$...$$`}</Latex> // If you want custom delimiters without prop

  correct:

  <Latex delimiters={[{ left: '$$', right: '$$', display: true }]}>...</Latex>

  While default delimiters are provided, custom delimiters for specific math environments should be passed via the `delimiters` prop as an array of objects.

Quickstart

This quickstart demonstrates how to import the `Latex` component, include the necessary KaTeX CSS, and render both inline and display-mode LaTeX equations within a React functional component. It also shows how to define and use custom KaTeX macros via the `macros` prop and configures `strict` mode.

import React from 'react';
import 'katex/dist/katex.min.css';
import Latex from 'react-latex-next';

function App() {
  const latexContent = `We give illustrations for the {1 + 2} processes $e^+e^-$, gluon-gluon and $\gamma\gamma \to W t\bar b$. 

This is a block equation: 
$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$

Here is an inline equation: $(ax^2 + bx + c = 0)$.

And a custom macro example: $\\f\\relax{x} = x$ is rendered using macros.`;

  return (
    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
      <h1>React LaTeX Example</h1>
      <Latex
        macros={{
          "\\f": "#1f(#2)"
        }}
        strict={false}
      >
        {latexContent}
      </Latex>
      <p>This example demonstrates rendering inline and block LaTeX, and using custom macros. The KaTeX CSS is imported directly.</p>
    </div>
  );
}

export default App;