Getting started

MathInput is a web component. It works in any framework, or none.

Install

npm install @mathinput/element
# React apps also:
npm install @mathinput/react

Use it in plain HTML or any framework

<script type="module">
  import "@mathinput/element/define";        // registers <math-input>
  import "@mathinput/element/mathinput.css"; // default styles
</script>

<math-input subject="maths" label="Expression" submit-on-enter></math-input>

<script type="module">
  const input = document.querySelector("math-input");
  input.addEventListener("submit", (e) => {
    const value = e.detail;           // see Output formats
    console.log(value.latex);         // x=\frac{1}{2}
    console.log(value.text);          // x = 1/2
  });
</script>

Give every field an accessible name with label, aria-label or aria-labelledby.

Use it in React

import { MathInput } from "@mathinput/react";
import "@mathinput/element/mathinput.css";

export function EquationField() {
  return (
    <MathInput
      subject="chemistry"
      label="Balanced equation"
      submitOnEnter
      onSubmit={(v) => save(v.doc)}
    />
  );
}

Pass value and onInput for a controlled field; it never resets the caret while the user types.

Show a stored expression

<math-input readonly latex="\frac{-b\pm\sqrt{b^{2}-4ac}}{2a}"></math-input>

Read-only fields have no caret or keypad and are read out by screen readers.

One expression at a time

Each field holds one expression. For multi-line work, such as the steps of a calculation, keep the list in your app: on submit, store e.detail, show it read-only, and call input.clear().

Fonts

The expression uses STIX Two Text if it is available, then Cambria Math and Times. Load STIX Two from your own assets (for example the @fontsource/stix-two-text package) or set another font with the math-font attribute or --mi-font-math.

API reference

Attributes

Properties

Methods

focus(), blur(), clear(), undo(), redo(), selectAll(), commit() (fires change), getValue(), setValue(doc), insert(nodeOrNodes), execute(command) where command is one of moveLeft, moveRight, moveUp, moveDown, moveHome, moveEnd, moveToNextPlaceholder, moveToPreviousPlaceholder, exitTemplate, deleteBackward, deleteForward, selectAll, clear, undo, redo.

Events

All events bubble and cross shadow roots.

The value is described in Output formats.

Keyboard

In chemistry, digits after an element become subscripts (H2O), and a two-letter element is recognised as you type (Cl).

Packages

Theming MathInput

MathInput ships a default look that works in light and dark mode. Everything visual can be changed without touching its source, in increasing depth:

1. Tokens — set --mi-* custom properties. Enough for most apps.
2. Classes — style the public mi-* classes in your own CSS.
3. Keypad — change keys, tabs and labels (see keypad-config.md).
4. Replace the stylesheet — skip mathinput.css and style the class contract from scratch.

Loading the styles

import "@mathinput/element/define";          // registers <math-input>
import "@mathinput/element/mathinput.css";   // default styles

All default rules are inside @layer mathinput, so any ordinary (unlayered) rule of yours wins without !important.

With Tailwind CSS v4

Import MathInput's Tailwind entry before Tailwind:

@import "@mathinput/element/tailwind.css";
@import "tailwindcss";

This fixes the layer order (theme, base, mathinput, components, utilities) so Tailwind utilities override the defaults, and exposes the tokens as theme values: bg-mi-key, text-mi-field-fg, bg-mi-key-template, rounded-mi-key, font-mi-math and so on. Consumers without Tailwind never need it.

Tokens

Set tokens on math-input (or any ancestor):

math-input {
  --mi-field-border-focus: #7c3aed;
  --mi-key-template-bg: #f3e8ff;
  --mi-key-template-fg: #5b21b6;
  --mi-key-variant-indicator: #db2777;
  --mi-key-radius: 6px;
}

Keep text at 4.5:1 contrast and boxes and indicators at 3:1; the default tokens are checked in CI.

Light and dark

theme="auto" (default) follows the operating system; theme="light" or theme="dark" forces one. To follow your app's own theme switch, set the attribute from your theme state, or define your own token values under your theme selector.

The "more options" indicator

Keys with extra options (hold, right-click, or Alt+↓) show a filled corner in --mi-key-variant-indicator. Change the shape with data-variant-indicator="dot" or "bar" on the element.

Classes

Structural classes are public API and are listed in the spec (§10.2); for example .mi-field, .mi-key[data-kind="template"], .mi-frac__bar, .mi-fence__side--ghost. State is exposed as attributes on the element: data-focused, data-readonly, data-disabled, data-form (phone|tablet|desktop), data-keypad (open|closed), data-subject.

Try the skins

Pick a skin to restyle the field below. The CSS it needs is shown underneath; copy it into your own stylesheet.

Configuring the keypad

Attributes

el.keypadOpen = true opens it from code; the keypad-toggle event reports changes.

Each subject's keypad offers every key it has. To fit it to a course, remove keys by topic or by id.

Changing keys

Patch the preset:

el.keypadLayout = {
  removeTabs: ["letters"],
  removeKeys: ["letter-t", "const-pi"],
  addKeys: {
    algebra: [{ id: "k", label: { text: "k" }, aria: "k", action: { type: "k" } }],
  },
};

A patch always starts from the preset for the field's subject. Removed keys also disappear from long-press menus, and a tab left empty is dropped.

Or replace it entirely with a full KeypadLayout ({ numberPad, tabs, navigation }); start from keypadPreset(subject) in @mathinput/core.

Key ids are stable. List them with:

import { keypadPreset } from "@mathinput/core";
const l = keypadPreset("maths");
console.log([l.numberPad, ...l.tabs].flatMap((t) => t.keys.map((k) => k.id)));

Removing topics

Keys for more advanced topics carry tags. Remove a whole topic with removeTags:

el.keypadLayout = { removeTags: ["calculus", "logarithms"] };

Your own keys can carry tags too (tags: ["my-topic"]).

Curriculum presets

Ready-made key sets for a curriculum are optional packages built on the same patches. @mathinput/presets-uk covers GCSE Foundation, GCSE Higher and A-level in England:

npm install @mathinput/presets-uk

import { ukKeypadPatch } from "@mathinput/presets-uk";

el.keypadLayout = ukKeypadPatch("gcse-higher");
// Combine with your own changes:
el.keypadLayout = { ...ukKeypadPatch("gcse-foundation"), removeTabs: ["letters"] };

ukKeypad(subject, level) returns the full trimmed layout, for example to list its key ids. In React, pass the patch as keypadLayout.

Key definitions

interface Key {
  id: string;
  aria: string;                      // accessible name, e.g. "fraction"
  label: { text: string }            // plain text
       | { tree: Row, active?: Position }  // a mini expression, drawn like the field
       | { icon: "left" | "right" | "backspace" | "enter" | "shift" | "keypad" | "table" }
       | { html: string };           // your own markup (you are responsible for it)
  action: { type: string }           // as if typed on a keyboard (subject rules apply)
        | { insert: Node | Node[] }
        | { template: Template, absorb?: boolean, prefix?: Node[] }
        | { command: CommandName }   // e.g. "moveLeft", "undo"
        | { bracket: "open" | "close" | "wrap", char: "(" | "[" | "{" | "|" }
        | { ui: "submit" | "shift" | "periodic-table" | "keypad-toggle" };
  variants?: Key[];                  // shown on long press; the key gets the indicator
  kind?: "digit" | "operator" | "template" | "letter" | "function" | "nav" | "primary" | "word";
}

Use tree labels for template keys so the key shows exactly what it inserts, with active marking the box the caret will land in. The tree builders in @mathinput/core (sup, frac, sqrt, …) make this short:

import { frac, sup } from "@mathinput/core";
const cubed = { id: "cubed", aria: "cubed", label: { tree: [sup("3")] }, action: { template: sup("3") } };

Output formats

Every event (input, change, submit) carries a value with:

Formats are computed when you first read them. Empty boxes appear as \square in LaTeX and ? in text, and brackets left open are closed in the output but reported in hasUnbalancedBrackets.

Recipes

Store and restore. Keep doc; it is the only lossless format.

save(JSON.stringify(event.detail.doc));
el.value = JSON.parse(saved);

Render somewhere else. Wrap latex in your renderer's delimiters (MathInput never adds them). KaTeX needs the mhchem extension for chemistry.

katex.render(event.detail.latex, target);

Show it read-only. A readonly field renders any stored expression and reads it out to screen readers: <math-input readonly latex="…">.

Search or index. Use text, which is stable and readable: x = 1/2 or x = 3.

Accessibility. Use spoken for a label or live region, or mathml where assistive technology reads MathML.

Language models. Send LaTeX in $…$, optionally with the text as a second reading:

const v = event.detail;
const prompt = `Expression: $${v.latex}$ (read as: ${v.text})`;

Reading formats back

@mathinput/core parses its own output and common variants:

import { fromLatex, fromText } from "@mathinput/core";
el.value = fromLatex("\\frac{x+1}{2}", "maths");
el.value = fromText("Mg + 2HCl -> MgCl2 + H2", "chemistry");

The latex attribute does the same for an initial value. Unsupported LaTeX raises ParseError (or a parse-error event from the element).

Without the element

All formats are pure functions in @mathinput/core, usable on a server: toLatex(doc), toText(doc), toSpoken(doc), toMathML(doc).