MathSnap

MathSnap is a lightweight, framework-agnostic wrapper around KaTeX that makes it easy to render beautiful math equations in your web applications. Works with React, Svelte, Vue, and vanilla JavaScript.

Features

• 🧮 Simplified API for rendering LaTeX math equations
• ⚛️ Components for React, Svelte, and Vue
• 📱 Responsive by default
• 🎨 Customizable styling options
• 🔍 Built-in error handling
• 📦 Tiny footprint with KaTeX as the only dependency
• 📝 TypeScript support

Installation

# npm
npm install mathsnap katex

# yarn
yarn add mathsnap katex

# pnpm
pnpm add mathsnap katex

Quick Start

React

import { ReactMathEquation, equations } from 'mathsnap';
import 'katex/dist/katex.min.css'; // Import KaTeX CSS

function App() {
  return (
    <div>
      <h1>Einstein's famous equation</h1>
      <ReactMathEquation equation={equations.einstein} displayMode={true} />
      
      <h2>Custom equation</h2>
      <ReactMathEquation equation="f(x) = \\int_{-\\infty}^{\\infty} \\hat{f}(\\xi)\\,e^{2 \\pi i \\xi x} \\,d\\xi" displayMode={true} />
    </div>
  );
}

Svelte

<script>
  import MathEquation from 'mathsnap/dist/svelte/MathEquation.svelte';
  import { equations } from 'mathsnap';
  import 'katex/dist/katex.min.css';
</script>

<h1>Quadratic Formula</h1>
<MathEquation equation={equations.quadratic} displayMode={true} />

<h2>Inline equation: <MathEquation equation="e^{i\\pi} + 1 = 0" /></h2>

Vue

<template>
  <div>
    <h1>Area of a Circle</h1>
    <MathEquation :equation="equations.circleArea" :displayMode="true" />
    
    <h2>With custom styling</h2>
    <MathEquation 
      equation="\\nabla \\times \\vec{B} = \\mu_0 \\vec{J} + \\mu_0 \\varepsilon_0 \\frac{\\partial \\vec{E}}{\\partial t}"
      :displayMode="true"
      :style="{ fontSize: '1.5rem', backgroundColor: '#f5f5f5', padding: '1rem' }"
    />
  </div>
</template>

<script>
import MathEquation from 'mathsnap/dist/vue/MathEquation.vue';
import { equations } from 'mathsnap';
import 'katex/dist/katex.min.css';

export default {
  components: {
    MathEquation
  },
  setup() {
    return { equations };
  }
}
</script>

Vanilla JavaScript

import { renderMath, equations } from 'mathsnap';
import 'katex/dist/katex.min.css';

// Get the container element
const container = document.getElementById('math-container');

// Render the equation
const { html } = renderMath({
  equation: equations.schrodinger,
  displayMode: true
});

// Set the HTML content
container.innerHTML = html;

API Reference

Core Functions

renderMath(options: MathOptions): { html: string; error: MathError }

Renders a LaTeX equation to an HTML string.

import { renderMath } from 'mathsnap';

const { html, error } = renderMath({
  equation: '\\sqrt{a^2 + b^2}',
  displayMode: true,
  katexOptions: {
    minRuleThickness: 0.05,
    macros: {
      '\\RR': '\\mathbb{R}'
    }
  }
});

if (!error.hasError) {
  console.log(html); // The rendered HTML
}

isValidEquation(equation: string): boolean

Checks if a string is a valid LaTeX equation.

import { isValidEquation } from 'mathsnap';

const isValid = isValidEquation('x^2 + y^2 = z^2');
console.log(isValid); // true

sanitizeEquation(equation: string): string

Sanitizes an equation to prevent code injection.

import { sanitizeEquation } from 'mathsnap';

const safeEquation = sanitizeEquation(userInput);

Predefined Equations

MathSnap comes with several predefined equations for common mathematical formulas:

import { equations } from 'mathsnap';

// Available equations:
// - equations.quadratic (Quadratic formula)
// - equations.einstein (E = mc²)
// - equations.pythagorean (a² + b² = c²)
// - equations.euler (Euler's identity)
// - equations.circleArea (Area of a circle)
// - equations.normalDistribution (Normal distribution)
// - equations.derivative (Derivative definition)
// - equations.integral (Integral definition)
// - equations.maxwellDivergenceE (Maxwell's equations - divergence of E)
// - equations.schrodinger (Schrödinger equation)

console.log(equations.euler); // e^{i\pi} + 1 = 0

React Component

import { ReactMathEquation } from 'mathsnap';

<ReactMathEquation 
  equation="E = mc^2"
  displayMode={true}
  className="custom-math"
  style={{ fontSize: '20px' }}
  as="div"
  katexOptions={{ colorIsTextColor: true }}
  onError={(error) => console.error(error)}
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | equation | string | (required) | The LaTeX equation to render | | displayMode | boolean | false | Whether to render in display mode (centered, block) or inline mode | | className | string | '' | Custom class name to add to the container | | style | React.CSSProperties | {} | Custom inline styles for the container | | as | 'div' \| 'span' \| 'p' | Based on displayMode | Container element to use | | katexOptions | KatexOptions | {} | Additional KaTeX options | | onError | (error: Error) => void | undefined | Error callback when rendering fails |

Svelte Component

<MathEquation 
  equation="E = mc^2"
  displayMode={true}
  className="custom-math"
  style="font-size: 20px"
  as="div"
  katexOptions={{ colorIsTextColor: true }}
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | equation | string | (required) | The LaTeX equation to render | | displayMode | boolean | false | Whether to render in display mode (centered, block) or inline mode | | className | string | '' | Custom class name to add to the container | | style | string | '' | Custom inline styles for the container | | as | 'div' \| 'span' \| 'p' | Based on displayMode | Container element to use | | katexOptions | KatexOptions | {} | Additional KaTeX options |

Vue Component

<MathEquation 
  equation="E = mc^2"
  :displayMode="true"
  className="custom-math"
  :style="{ fontSize: '20px' }"
  as="div"
  :katexOptions="{ colorIsTextColor: true }"
  @error="handleError"
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | equation | string | (required) | The LaTeX equation to render | | displayMode | boolean | false | Whether to render in display mode (centered, block) or inline mode | | className | string | '' | Custom class name to add to the container | | style | Object | {} | Custom inline styles for the container | | as | 'div' \| 'span' \| 'p' | Based on displayMode | Container element to use | | katexOptions | KatexOptions | {} | Additional KaTeX options |

Advanced Usage

Custom KaTeX Options

You can pass any valid KaTeX options through the katexOptions prop:

<ReactMathEquation 
  equation="\color{blue}{f(x) = sin(x)}"
  katexOptions={{
    colorIsTextColor: true,
    macros: {
      "\\RR": "\\mathbb{R}"
    }
  }}
/>

Responsive Equations

MathSnap components are responsive by default, with max-width: 100% and overflow-x: auto to handle large equations gracefully.

Error Handling

MathSnap provides error handling out of the box:

<ReactMathEquation 
  equation="a = "  // Invalid equation
  onError={(error) => {
    console.error('Math rendering error:', error.message);
    // Handle the error, e.g., show a notification
  }}
/>

Browser Support

MathSnap works in all modern browsers that support KaTeX.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT