MathField

When to use

A student has to type $\frac{5}{6}$ into a blank, or a teacher authoring questions does not know how to write \sqrt{}: the user sees a calculator-like box, what they type is already LaTeX, and the value you receive goes straight into Formula for typesetting or into gradeObjective for grading. To insert a formula into a run of text, use MathTextarea and pass this component as its visualEditor; it wraps the result in $…$ and inserts at the caret. MathField itself never emits $.

For display only, use Formula.

Installation

mathlive is an optional peer; the component only works once it is installed:

To use createCasComparator, also install @cortex-js/compute-engine (the dependency mathlive pins; it is usually already in node_modules, and installing it explicitly keeps the bundler's resolution independent of hoisting):

Import the fonts once (the root layout in Next, main.tsx in Vite). Missing fonts fall back to system fonts; nothing goes blank:

Peer floors are mathlive >=0.110.0 and @cortex-js/compute-engine >=0.58.0: only the versions we tested. Between MathLive 0.9x and 0.10x the semantics of menuItems and the virtual keyboard policy changed, so a lower floor would promise untested combinations.

Import

It lives on its own subpath rather than in @hulianui/ui/math: MathLive plus the Compute Engine is a lazy chunk of several hundred KB, and only pages that really need visual input or CAS grading should pay for it. @hulianui/ui/math itself contains zero MathLive.

Props

MathFieldProps extends `MathFieldLikeProps`; the first six rows are that contract.

Events

createCasComparator

Uses the Compute Engine to decide whether two LaTeX strings are mathematically equivalent: \frac{1}{2} vs 0.5 and 2x+1 vs 1+2x are both true. The result is a synchronous comparator that feeds the equivalent option of gradeObjective (tier 3, consulted only when the literal and normalized tiers both disagree). $…$ / $$…$$ / \(…\) are stripped from both sides first (stripMathDelimiters); a parse failure, an empty string, or any exception yields false, because grading should rather miss a match than invent one.

It is async: the Compute Engine is not bundled with mathlive, so the first call runs import() and later calls reuse the same engine instance. Without @cortex-js/compute-engine it throws ComputeEngineUnavailableError with the install command in the message.

The server is the grading source of truth (see the gradeObjective section in the Formula docs): this comparator gives instant feedback and authoring self-checks; official scores come from the server.

SSR and loading

The component has three states, exposed as data-status on data-slot="math-field": loading / ready / unavailable.

• loading: the server and the first client frame both render only a Skeleton of the same size, so the HTML matches and there is no hydration mismatch.
• ready: once import("mathlive") in useEffect succeeds, the real element is created with document.createElement("math-field") and kept in sync with the controlled value.
• unavailable: mathlive is missing, or the resolver picked MathLive's SSR build (no MathfieldElement). An Alert with the install command is rendered, nothing throws, and a static export never fails because of it. warnOnce fires once in development.

Next App Router works out of the box; the component is already a client component and needs no next/dynamic. In Vite you may add optimizeDeps.include: ["mathlive", "@cortex-js/compute-engine"] to avoid a mid-session re-optimization the first time it opens.

Virtual keyboard

MathLive's virtual keyboard is a page-level singleton (window.mathVirtualKeyboard); every MathField on the page shares it, and keyboardLayouts, when given, is written into that singleton, so the last mounted field wins. Desktop authoring usually sets virtualKeyboard="off"; touch-screen answering keeps the default auto.

Theming

MathLive reads its colors from CSS variables; the component pins them to Hulian tokens so light and dark follow the theme:

The frame shares the border and focus ring of Input; MathLive's built-in context menu is disabled (menuItems = []).

Localization

The only copy is the loading placeholder's accessible name and the missing-dependency hint, read from components.mathField of ConfigProvider; the source of truth is math-field.locale.ts (MATH_FIELD_LOCALE_ZH / MATH_FIELD_LOCALE_EN).

Pitfalls

• The value is LaTeX without `$`. To insert it into a stem, go through the visualEditor of MathTextarea (which adds the $); concatenating value into a stem yourself yields bare notation without delimiters.
• Inject the component, not an element: mathField={MathField} and visualEditor={MathField}, never <MathField />.
• In jsdom, mathlive resolves to its SSR build and the component shows the install hint: in consumer unit tests, vi.mock("mathlive") with a fake element that implements only getValue / setValue, or assert the first-frame skeleton only.
• MathLive's `setValue` requires a mounted element; the component appends first and writes afterwards. Do the same when you drive <math-field> yourself.

Related

• MathTextarea: the MathFieldLikeProps contract and the visualEditor injection point
• QuestionAnswer: blankInput="math" plus mathField
• QuestionEditor: forwards visualEditor to every MathTextarea
• Formula: typesetting and the question-domain functions of @hulianui/ui/math (gradeObjective)
• Consuming guide for the math components: what each entry costs, SSR, grading source of truth