Interacting with a Mathfield

Reading the Content of a Mathfield

The content of a mathfield is available by reading the value property of the mathfield element, just like with a <textarea>.

To be notified as soon as the content of the mathfield is modified listen for an 'input' event.

Try: modify the 'input' event below to a 'change' event. Notice how the 'change' event is only sent if you press the Return or Enter key, or when the mathfield loses focus and the content has been modified.

document.getElementById('formula').addEventListener('input',(ev) => { // `ev.target` is an instance of `MathfieldElement` console.log(ev.target.value); });
<script src="//unpkg.com/mathlive/dist/mathlive.min.js"></script> <math-field id="formula"> x=\frac{-b\pm \sqrt{b^2-4ac}}{2a} </math-field>

Reading the value property is equivalent to calling the getValue() method with no argument.

To control how the result is formatted, pass options to getValue(). For example to get the content as a MathJSON expression, use getValue('math-json').

The MathJSON format is a lightweight data interchange format for mathematical notation. Learn more about MathJSON.

Try: Other formats are available: change 'math-json' to 'spoken-text'.

<script src="//unpkg.com/mathlive/dist/mathlive.min.js"></script> <math-field id="formula"> x=\frac{-b\pm \sqrt{b^2-4ac}}{2a} </math-field>
const mf = document.getElementById('formula'); mf.addEventListener('input',(ev) => { // `ev.target` is an instance of `MathfieldElement` console.log(ev.target.getValue('math-json')); });

Changing the Content of a Mathfield

You can change the value of the mathfield programatically. In the example below, the Latex input field is editable and is reflected in the mathfield (and vice-versa).

Note that we use the suppressChangeNotifications option when changing the content of the mathfield, to prevent a 'input' event from being triggered and creating an infinite loop.

import 'mathlive'; const mf = document.getElementById('formula'); mf.addEventListener('input',(ev) => { document.getElementById('latex').value = mf.value; }); // document.getElementById('latex').value = mf.value; // // Listen for changes in the latex text field, and reflect its value in // the mathfield. // document.getElementById('latex'). addEventListener('input', (ev) => { mf.setValue( ev.target.value, {suppressChangeNotifications: true} ); });
<label>Mathfield</label> <math-field id="formula"> x=\frac{-b\pm \sqrt{b^2-4ac}}{2a} </math-field> <label>Latex</label>

Applying Style to a Mathfield

The text color (“ink”) and background color (“paper”), as well as other stylistic attributes, can be changed on a mathfield, or a portion of a mathfield using applyStyle().

This style applies to the content of the formula and will be reflected in the Latex output. To change the appearance of the mathfield but not the content of the formula, see Customizing.

import 'mathlive'; const mf = document.getElementById('formula'); // Change the background color of the entire mathfield mf.applyStyle( {backgroundColor: 'yellow' }, {range: [0, -1]} );
<math-field id="formula"> x=\frac{-b\pm \sqrt{b^2-4ac}}{2a} </math-field>

To change the style of a portion of the mathfield, specify a selection range to applyStyle().

import 'mathlive'; const mf = document.getElementById('formula'); // Change the color and size of the first two characters of the mathfield mf.applyStyle({color: "red", fontSize: 7 }, { range: [0, 2] });
<math-field id="formula"> x=\frac{-b\pm \sqrt{b^2-4ac}}{2a} </math-field>

Detecting a Click on a Mathfield

In most cases Mathlive will respond to mouse and keyboard interactions with the mathfield. However, in some cases it might be useful to detect when a mathfield is clicked on. For example, you could display one or more read-only mathfields in a list and prompt the user to pick one by clicking on it.

In general, to be notified of an event, use mf.addEventListener(). This include some generic events, as well as some that are specific to mathfields. Events that target a DOM element inside the mathfield (inside the shadow DOM) will bubble and be retargeted to appear as if they had targeted the mathfield (that is, the evt.target will be the mathfield itself).

This include the following standard events:

  • change: Return or Enter key was pressed
  • blur, focus, focusin, focusout
  • mousedown, mouseup, mousemove, mouseout, mouseover`
  • wheel
  • beforeinput, input, keydown, keyup
  • all the pointer events such as pointerdown, pointerup, etc… and all the touch events

As well as these mathfield specific events:

  • mount: the mathfield has been connected to the DOM
  • unmount: the mathfield is no longer connected to the DOM
  • math-error: syntax and other errors
  • keystroke: general keyboard interactions
  • focus-out: tab key interactions
  • move-out: arrow key interactions
  • mode-change: change to math, text or latex mode
  • read-aloud-status-change
  • selection-change
  • undo-state-change

The click event may be dispatched in some cases. However, this event should be avoided. It is a synthetic event, meaning it’s generated by the browser based on some heuristic that tries to detect a pointerdown followed by a pointerup on the same DOM element. However, interacting with a mathfield may change its DOM elements (to display the selection for example), the browser may not be able to reliably trigger this event.

Instead, to detect when a mathfield is being clicked on, listern for a focus event or a pointerdown event. The focus event has the benefit of working with both mouse and keyboard, which makes this solution more accessible.

Detecting When the User has Finished Editing a Mathfield

To detect when the user presses the Return or Enter key in a mathfield, listen for the change event. Note that this event is not fired when in Latex editing mode, where Return or Enter is used to exit the mode.

Interacting with the Clipboard

Users can export the content of the mathfield by using standard Copy/Cut commands (ctrl/command+X and ctrl/command+C).

Multiple flavors are put on the clipboard, and the recipient of the Paste operation can pick whichever is most appropriate:
text/plain Latex wrapped with a \begin{equation*} and \end{equation*}.
application/x-latex Raw Latex
application/json A MathJSON representation of the formula.
application/mathml+xml A MathML representation of the formula.

The Latex in the text/plain flavor is “wrapped” to make it easier for the recipient of the paste to recognize that this content is in Latex format. There isn’t really a standard format for this, but testing of several Latex-capable editors has shown that \begin{equation*} was the most commonly recognized.

For improved interoperability, the exported Latex uses the latex-expanded format. In this format, macros that may be used in the formula are expanded to their definition. For example, if the \differentialD command is used in the formula, it is exported as its corresponding definition, \mathrm{d}. .

To customize the content of the text/plain flavor, use the onExport() hook.

For example, to wrap the exported latex with <math>...</math> instead:

mf.setOptions({onExport: (mf, latex) => `<math>${latex}</math>`});

To export the “raw” (not expanded) Latex), use:

mf.setOptions({onExport: (mf, latex, range) => 
  `\\(${mg.getValue(range, 'latex')}\\)`
});

The exported format doesn’t have to be Latex. To export ASCIIMath instead:

mf.setOptions({onExport: (mf, latex, range) => 
  "`" + mg.getValue(range, 'ascii-math') + "`".
});

The standard delimiter for AsciiMath is the ` (backtick) character .

Next: Customizing a Mathfield: controlling its appearance and behavior
Next: Understand in depth the Lifecycle of a MathfieldElement: construction, interaction with the DOM and when you can communicate with it