better-react-mathjax

To use MathJax in your React application, you must follow a two-step pattern:

1. Wrap your app in MathJaxContext: This component is responsible for downloading MathJax and providing it to all child components. You should only use one MathJaxContext in your entire application. By default, it imports MathJax from a CDN.
2. Use MathJax components for math content: Place MathJax components at various levels of your component tree to render actual math. The content inside a MathJax component can range from a single string of math to a large subtree of the DOM.

Note: Both components include the "use client" directive, making them client components in frameworks like Next.js.

const App = () => {
   return (
       <MathJaxContext>
           {/* APP CONTENT */}
       </MathJaxContext>
   )
}

const Component = () => {
   return (
       <div>
           <MathJax>{ /* math content */ }</MathJax>
           <p>Text with <MathJax>{ /* math content */ }</MathJax></p>
       </div>
   )
}

A common challenge is preventing users from seeing raw math strings before MathJax has finished typesetting. Depending on your content type, use these strategies:

For Static Content

• hideUntilTypeset: Set this prop to 'first' on individual MathJax components or on the MathJaxContext to hide content until the initial typesetting is complete.
• Coordinated Hiding: Use onInitTypeset on components or onStartUp/onLoad on the MathJaxContext to show entire page sections only after typesetting is finished.

For Dynamic Content

• dynamic={true}: Ensure this is set so that updates are re-typeset.
• hideUntilTypeset='every': Set this to 'every' to hide content during every update. This may cause a short blink but prevents showing unformatted math.
• renderMode='pre': This mode typesets the math before inserting it into the DOM. This is often the most effective way to eliminate flashes, though it may limit MathJax's ability to adapt to the surrounding context.

To ensure correct typesetting and performance, follow these guidelines:

• Avoid Nesting: Do not nest MathJax components. This causes the same math content to be typeset multiple times unnecessarily.
• Handle Dynamic Content Carefully: When the dynamic property is set to true, avoid mixing math expressions with literal text within the same DOM element due to React/DOM manipulation conflicts.
  • Do: <p>{ "An example is the equation $${num}x^4 = 100$" }</p>
  • Do: <p>An example is the equation <span>{ "$${num}x^4 = 100$" }</p>
  • Don't: <p>An example is the equation ${num}x^4 = 100$</p>
  • Don't: <p>An example is the equation { "$${num}x^4 = 100$" }</p>
• Manage Re-renders: Do not wrap content that re-renders on its own without the MathJax component also re-rendering. If a child re-renders but the parent MathJax component does not, the math will not be typeset anew. If you encounter this, wrap smaller portions of the math in their own MathJax components so that the state change triggers a re-render of the component containing the math.
• Optimize Performance: If typesetting many small components is slow, group them. Replace many individual MathJax components with a single MathJax component wrapping a larger portion of the DOM sub-tree to reduce typesetting overhead.