MathLive

module "mathfield-element"interface MathfieldElementAttributes Permalink

These attributes of the <math-field> element correspond to the [MathfieldOptions] properties.

default-mode: string Permalink

fonts-directory: string Permalink

horizontal-spacing-scale: string Permalink

Scaling factor to be applied to horizontal spacing between elements of the formula. A value greater than 1.0 can be used to improve the legibility.

deprecated

Use registers \thinmuskip, \medmuskip and \thickmuskip

inline-shortcut-timeout: string Permalink

Maximum time, in milliseconds, between consecutive characters for them to be considered part of the same shortcut sequence.

A value of 0 is the same as infinity: any consecutive character will be candidate for an inline shortcut, regardless of the interval between this character and the previous one.

A value of 750 will indicate that the maximum interval between two characters to be considered part of the same inline shortcut sequence is 3/4 of a second.

This is useful to enter “±” as a sequence of two characters, while also supporting the “±” shortcut with the same sequence.

The first result can be entered by pausing slightly between the first and second character if this option is set to a value of 250 or so.

Note that some operations, such as clicking to change the selection, or losing the focus on the mathfield, will automatically timeout the shortcuts.

keypress-sound: string Permalink

When a key on the virtual keyboard is pressed, produce a short audio feedback.

The value of the properties should a string, the name of an audio file in the soundsDirectory directory or ‘none’ to supress the sound.

keypress-vibration: boolean Permalink

letter-shape-style: string Permalink

locale: string Permalink

The locale (language + region) to use for string localization.

If none is provided, the locale of the browser is used.

math-mode-space: string Permalink

The Latex string to insert when the spacebar is pressed (on the physical or virtual keyboard). Empty by default. Use \; for a thick space, \: for a medium space, \, for a thin space.

plonk-sound: string Permalink

Sound played to provide feedback when a command has no effect, for example when pressing the spacebar at the root level.

The property is either:

• a string, the name of an audio file in the soundsDirectory directory
• ‘none’ to turn off the sound

read-only: boolean Permalink

When true, the user cannot edit the mathfield.

remove-extraneous-parentheses: boolean Permalink

shared-virtual-keyboard-target-origin: string Permalink

Specify the targetOrigin parameter for postMessage to send control messages from child to parent frame to remote control of mathfield component.

Default: window.origin

smart-fence: boolean Permalink

When true and an open fence is entered via typedText() it will generate a contextually appropriate markup, for example using \left...\right if applicable.

When false, the literal value of the character will be inserted instead.

smart-mode: boolean Permalink

When true, during text input the field will switch automatically between ‘math’ and ‘text’ mode depending on what is typed and the context of the formula. If necessary, what was previously typed will be ‘fixed’ to account for the new info.

For example, when typing “if x >0”:

Type	Interpretation
“i”	math mode, imaginary unit
“if”	text mode, english word “if”
“if x”	all in text mode, maybe the next word is xylophone?
“if x >”	“if” stays in text mode, but now “x >” is in math mode
“if x > 0”	“if” in text mode, “x > 0” in math mode

Smart Mode is off by default.

Manually switching mode (by typing alt/option+=) will temporarily turn off smart mode.

Examples

• slope = rise/run
• If x > 0, then f(x) = sin(x)
• x^2 + sin (x) when x > 0
• When x<0, x^{2n+1}<0
• Graph x^2 -x+3 =0 for 0<=x<=5
• Divide by x-3 and then add x^2-1 to both sides
• Given g(x) = 4x – 3, when does g(x)=0?
• Let D be the set {(x,y)|0<=x<=1 and 0<=y<=x}
• \int_{the unit square} f(x,y) dx dy
• For all n in NN

smart-superscript: boolean Permalink

When true, when a digit is entered in an empty superscript, the cursor leaps automatically out of the superscript. This makes entry of common polynomials easier and faster. If entering other characters (for example “n+1”) the navigation out of the superscript must be done manually (by using the cursor keys or the spacebar to leap to the next insertion point).

When false, the navigation out of the superscript must always be done manually.

speech-engine: string Permalink

speech-engine-rate: string Permalink

speech-engine-voice: string Permalink

text-to-speech-markup: string Permalink

text-to-speech-rules: string Permalink

use-shared-virtual-keyboard: boolean Permalink

When true, use a shared virtual keyboard for all the mathfield elements in the page, even across iframes.

When setting this option to true, you must create the shared virtual keyboard in the the parent document:

import { makeSharedVirtualKeyboard } from 'mathlive';

    makeSharedVirtualKeyboard({
        virtualKeyboardToolbar: 'none',
    });

Default: false

virtual-keyboard-layout: string Permalink

virtual-keyboard-mode: "auto" | "manual" | "onfocus" | "off" Permalink

• 'manual': pressing the virtual keyboard toggle button will show or hide the virtual keyboard. If hidden, the virtual keyboard is not shown when the field is focused until the toggle button is pressed.
• 'onfocus': the virtual keyboard will be displayed whenever the field is focused and hidden when the field loses focus. In that case, the virtual keyboard toggle button is not displayed.
• 'off': the virtual keyboard toggle button is not displayed, and the virtual keyboard is never triggered.

If the setting is empty, it will default to 'onfocus' on touch-capable devices and to 'off' otherwise.

virtual-keyboard-theme: string Permalink

The visual theme used for the virtual keyboard.

If empty, the theme will switch automatically based on the device it’s running on. The two supported themes are ‘material’ and ‘apple’ (the default).

virtual-keyboards: string Permalink

A space separated list of the keyboards that should be available. The keyboard 'all' is synonym with 'numeric', 'functions'``, ‘symbols’`` 'roman' and 'greek',

The keyboards will be displayed in the order indicated.

module "mathfield-element"FocusOutEvent Permalink

The focus-out event signals that the mathfield has lost focus through keyboard navigation with the tab key.

The event detail.direction property indicates if tab (direction === "forward") or shift+tab (`direction === “backward”) was pressed which can be useful to decide which element to focus next.

If the event is canceled by calling ev.preventDefault(), no change of focus will occur (but you can manually change the focus in your event handler: this gives you an opportunity to override the default behavior and selects which element should get the focus, or to prevent from a change of focus altogether).

If the event is not canceled, the default behavior will take place, which is to change the focus to the next/previous focusable element.

mfe.addEventListener('focus-out', (ev) => {
 console.log("Losing focus ", ev.detail.direction);
});

module "mathfield-element"KeystrokeEvent Permalink

The keystroke event is fired when a keystroke is about to be procesed. The event is cancellable, which wills suprress further handling of the event.

module "mathfield-element"MathErrorEvent Permalink

The math-error custom event signals an error while parsing an expression.

document.getElementById('mf').addEventListener('math-error', (ev) => {
 const err = ev.detail;
 console.warn(err.code + (err.arg ? ': ' + err.arg : '') +
        '\n%c|  ' + err.before + '%c' + err.after +
        '\n%c|  ' + String(' ').repeat(err.before.length) +
        '▲',
        'font-weight: bold',
        'font-weight: normal; color: rgba(160, 160, 160)',
        'font-weight: bold; color: hsl(4deg, 90%, 50%)'
    );
});

module "mathfield-element"MoveOutEvent Permalink

The move-out event signals that the user pressed an arrow key but there was no navigation possible inside the mathfield.

This event provides an opportunity to handle this situation, for example by focusing an element adjacent to the mathfield.

If the event is canceled (i.e. evt.preventDefault() is called inside your event handler), the default behavior is to play a “plonk” sound.

module "options"setKeyboardLayout Permalink

Change the current physical keyboard layout.

Note that this affects some keybindings, but not general text input.

If set to auto the keyboard layout is guessed.

module "options"setKeyboardLayoutLocale Permalink

Change the current physical keyboard layout to a layout that matches the specified locale, if one is available.

Note that this affects some keybindings, but not general text input.

module "options"interface MathfieldHooks Permalink

These hooks provide an opportunity to intercept or modify an action. When their return value is a boolean, it indicates if the default handling should proceed.

onExport: (from: Mathfield, latex: string, range: Range): string Permalink

This hooks is invoked when the user has requested to export the content of the mathfield, for example when pressing ctrl/command+C.

This hook should return as a string what should be exported.

The range argument indicates which portion of the mathfield should be exported. It is not always equal to the current selection, but it can be used to export a format other than Latex.

By default this is:

 return `\\begin{equation*}${latex}\\end{equation*}`;

onKeystroke: (sender: Mathfield, keystroke: string, ev?: KeyboardEvent): boolean Permalink

A hook invoked when a keystroke is about to be processed.

• keystroke: a string describing the keystroke
• ev: the native keyboard event

Return false to stop the handling of the event.

deprecated

Use corresponding events of MathfieldEvent instead

onMoveOutOf: (sender: Mathfield, direction: "forward" | "backward" | "upward" | "downward"): boolean Permalink

A hook invoked when keyboard navigation would cause the insertion point to leave the mathfield.

• direction indicates the direction of the navigation, either "forward" or "backward" or "upward" or "downward".

Return false if the move has been handled by the hook.

Return true for the default behavior, which is playing a “plonk” sound.

deprecated

Use corresponding events of MathfieldEvent instead

onTabOutOf: (sender: Mathfield, direction: "forward" | "backward"): boolean Permalink

This hook is invoked when pressing tab (or shift-tab) would cause the insertion point to leave the mathfield.

direction indicates the direction of the navigation.

By default, the insertion point jumps to the next/previous focussable element.

deprecated

Use corresponding events of MathfieldEvent instead

module "options"interface MathfieldListeners Permalink

The methods provide a notification that an event is about to occur or has occured.

In general instead of using this interface you should be listening to the corresponding event on MathfieldElement, i.e.

mfe.addEventListener('input', (ev) => {
console.log(ev.target.value);
});

onBlur: (sender: Mathfield): void Permalink

The mathfield has lost keyboard focus

onCommit: (sender: Mathfield): void Permalink

onContentDidChange: (sender: Mathfield): void Permalink

onContentWillChange: (sender: Mathfield): void Permalink

onFocus: (sender: Mathfield): void Permalink

The mathfield has gained keyboard focus

onModeChange: (sender: Mathfield, mode: ParseMode): void Permalink

onReadAloudStatus: (sender: Mathfield): void Permalink

onSelectionDidChange: (sender: Mathfield): void Permalink

onSelectionWillChange: (sender: Mathfield): void Permalink

onUndoStateDidChange: UndoStateChangeListener Permalink

onUndoStateWillChange: UndoStateChangeListener Permalink

module "options"interface VirtualKeyboardDefinition Permalink

classes?: string Permalink

command?: string | string[] Permalink

label: string Permalink

layer?: string Permalink

layers?: string[] Permalink

tooltip?: string Permalink

module "options"interface VirtualKeyboardKeycap Permalink

aside: string Permalink

Markup displayed with the key label (for example to explain what the symbol of the key is)

class: string Permalink

CSS classes to apply to the keycap.

• tex: use the TeX font for its label. Using the tex class is not necessary if using the latex property to define the label.
• modifier: a modifier (shift/option, etc…) keycap
• small: display the label in a smaller size
• action: an “action” keycap (for arrows, return, etc…)
• separator w5: a half-width blank used as a separator. Other widths include w15 (1.5 width), w20 (double width) and w50 (five-wide, used for the space bar).
• bottom, left, right: alignment of the label

command: Selector | [Selector, ...any[]] Permalink

Command to perform when the keycap is pressed

content: string Permalink

HTML markup to represent the keycap.

This property is only useful when using a custom keycap shape or appearance. Usually, setting the label property is sufficient.

insert: string Permalink

Latex fragment to insert when the keycap is pressed (ignored if command is specified)

key: string Permalink

Key to insert when keycap is pressed (ignored if command, insert or latex is specified)

label: string Permalink

The HTML markup displayed for the keycap

latex: string Permalink

Label of the key as a Latex expression, also the Latex inserted if no command or insert property is specified.

shifted: string Permalink

Markup for the label of the key when the shift key is pressed

shiftedCommand: Selector | [Selector, ...any[]] Permalink

Command to perform when the shifted key is pressed

variants: string | Partial<VirtualKeyboardKeycap>[] Permalink

A set of keycap variants displayed on a long press

variants: [
 '\\alpha',    // Same label as value inserted
 { latex: '\\beta', label: 'beta' }
]

module "options"interface VirtualKeyboardLayer Permalink

backdrop: string Permalink

A CSS class name to customize the appearance of the background of the layer

container: string Permalink

A CSS class name to customize the appearance of the container the layer

rows: Partial<VirtualKeyboardKeycap>[][] Permalink

The rows of keycaps in this layer

styles: string Permalink

The CSS stylesheet associated with this layer

module "options"CoreOptions Permalink

module "options"EditingOptions Permalink

module "options"InlineShortcutDefinition Permalink

An inline shortcut can be specified as a simple string or as an object literal with additional options:

    config.inlineShortcuts = {
     half: '\\frac{1}{2}',
     in: {
         mode: 'math',
         after: 'space+letter+digit+symbol+fence',
         value: '\\in',
     },
 };

When using a string, the shortcut will apply in any mode, and regardless of the characters surrounding it.

When using an object literal the value key is required an indicate the shortcut substitution.

The mode key, if present, indicate which mode this shortcut will apply in, either 'math' or 'text'. If the key is not present the shortcut apply in all modes.

The 'after' key, if present, indicate in what context (surrounding characters) the shortcut will apply. One or more values can be specified, separated by a ‘|’ character. If any of the values match, the shortcut will be applicable.

Possible values are:

module "options"InlineShortcutsOptions Permalink

module "options"Keybinding Permalink

A keybinding associates a combination of physical keyboard keys with a command.

For example:

{
     "key": "cmd+a",
     "command": "selectAll",
},
{
     "key": 'ctrl+[Digit2]',
     "ifMode": 'math',
     "command": ['insert', '\\sqrt{#0}'],
}

module "options"KeyboardLayoutName Permalink

See setKeyboardLayout.

module "options"KeyboardOptions Permalink

module "options"LayoutOptions Permalink

module "options"LocalizationOptions Permalink

module "options"MathfieldOptions Permalink

module "options"OriginValidator Permalink

Specify behaviour for origin validation.

module "options"RemoteVirtualKeyboardOptions Permalink

module "options"TextToSpeechOptions Permalink

module "options"UndoStateChangeListener Permalink

module "options"VirtualKeyboardOptions Permalink

module "options"VirtualKeyboardToolbarOptions Permalink

module "mathlive"convertLatexToMarkup Permalink

Convert a LaTeX string to a string of HTML markup.

    <link rel="stylesheet" href="https://unpkg.com/mathlive/dist/mathlive-static.css" />

module "mathlive"convertLatexToMathMl Permalink

Convert a LaTeX string to a string of MathML markup.

module "mathlive"convertLatexToSpeakableText Permalink

Convert a LaTeX string to a textual representation ready to be spoken

console.log(convertLatexToSpeakableText('\\frac{1}{2}'));
// 'half'

module "mathlive"renderMathInDocument Permalink

Transform all the elements in the document body that contain LaTeX code into typeset math.

Read Getting Started.

import { renderMathInDocument } from 'https://unpkg.com/mathlive/dist/mathlive.min.mjs';
document.addEventListener("load", () => {
    renderMathInDocument();
});

module "mathlive"renderMathInElement Permalink

Transform all the children of element that contain LaTeX code into typeset math, recursively.

Read Getting Started.

module "mathlive"makeSharedVirtualKeyboard Permalink

Initialize remote client for mathfield elements rendered in child frames. This client instance control focus between multiple frames and mathfield elements and renders the virtual keyboard with required options passed by params of this method.

module "mathlive"version Permalink

Current version: 0.69.4

The version string of the SDK using the semver convention:

MAJOR.MINOR.PATCH

• MAJOR is incremented for incompatible API changes
• MINOR is incremented for new features
• PATCH is incremented for bug fixes

module "mathlive"AutoRenderOptions Permalink

module "mathfield"interface Model Permalink

mathfield: Mathfield Permalink

module "mathfield"ApplyStyleOptions Permalink

module "mathfield"FindOptions Permalink

module "mathfield"InsertOptions Permalink