Mathfield API Reference

Mathfield

MathfieldElement

The MathfieldElement class is a DOM element that provides a math input field.

It is a subclass of the standard HTMLElement class and as such inherits all of its properties and methods, such as style, tabIndex, addEventListener(), getAttribute(), etc...

The MathfieldElement class provides additional properties and methods to control the display and behavior of <math-field> elements.

To instantiate a MathfieldElement use the <math-field> tag in HTML. You can also instantiate a MathfieldElement programmatically using new MathfieldElement().

// 1. Create a new MathfieldElement
const mf = new MathfieldElement();

// 2. Attach it to the DOM
document.body.appendChild(mf);

// 3. Modifying options after construction
mf.addEventListener("mount"), () => {
 mf.smartFence = true;
});

Read more about customizing the appearance and behavior of the mathfield in the Customizing the Mathfield guide.

MathfieldElement CSS Variables

To customize the appearance of the mathfield, declare the following CSS variables (custom properties) in a ruleset that applies to the mathfield.

math-field {
 --hue: 10       // Set the highlight color and caret to a reddish hue
}

Alternatively you can set these CSS variables programatically:

document.body.style.setProperty("--hue", "10");

Read more about the CSS variables available for customization.

You can customize the appearance and zindex of the virtual keyboard panel with some CSS variables associated with a selector that applies to the virtual keyboard panel container.

Read more about customizing the virtual keyboard appearance

MathfieldElement CSS Parts

In addition to the CSS variables, the mathfield exposes CSS parts that can be used to style the mathfield

For example, to hide the menu button:

math-field::part(menu-toggle) {
 display: none;
}

MathfieldElement Attributes

An attribute is a key-value pair set as part of the tag:

<math-field letter-shape-style="tex"></math-field>

The supported attributes are listed in the table below with their corresponding property.

The property can also be changed directly on the MathfieldElement object:

 mf.value = "\\sin x";
 mf.letterShapeStyle = "text";

The values of attributes and properties are reflected, which means you can change one or the other, for example:

mf.setAttribute('letter-shape-style',  'french');
console.log(mf.letterShapeStyle);
// Result: "french"

mf.letterShapeStyle ='tex;
console.log(mf.getAttribute('letter-shape-style');
// Result: 'tex'

An exception is the value property, which is not reflected on the value attribute: for consistency with other DOM elements, the value attribute remains at its initial value.

Attribute	Property
disabled	mf.disabled
default-mode	mf.defaultMode
letter-shape-style	mf.letterShapeStyle
min-font-scale	mf.minFontScale
max-matrix-cols	mf.maxMatrixCols
popover-policy	mf.popoverPolicy
math-mode-space	mf.mathModeSpace
read-only	mf.readOnly
remove-extraneous-parentheses	mf.removeExtraneousParentheses
smart-fence	mf.smartFence
smart-mode	mf.smartMode
smart-superscript	mf.smartSuperscript
inline-shortcut-timeout	mf.inlineShortcutTimeout
script-depth	mf.scriptDepth
value	value
math-virtual-keyboard-policy	mathVirtualKeyboardPolicy

See the corresponding property for more details about these options.

In addition, the following global attributes can also be used:

• class
• data-*
• hidden
• id
• item*
• style
• tabindex

MathfieldElement Events

Listen to these events by using mf.addEventListener(). For events with additional arguments, the arguments are available in event.detail.

Event Name	Description
beforeinput	The value of the mathfield is about to be modified.
input	The value of the mathfield has been modified. This happens on almost every keystroke in the mathfield. The evt.data property includes a copy of evt.inputType. See InputEvent
change	The user has committed the value of the mathfield. This happens when the user presses Return or leaves the mathfield.
selection-change	The selection (or caret position) in the mathfield has changed
mode-change	The mode (math, text) of the mathfield has changed
undo-state-change	The state of the undo stack has changed. The evt.detail.type indicate if a snapshot was taken or an undo performed.
read-aloud-status-change	The status of a read aloud operation has changed
before-virtual-keyboard-toggle	The visibility of the virtual keyboard panel is about to change. The evt.detail.visible property indicate if the keyboard will be visible or not. Listen for this event on window.mathVirtualKeyboard
virtual-keyboard-toggle	The visibility of the virtual keyboard panel has changed. Listen for this event on window.mathVirtualKeyboard
geometrychange	The geometry of the virtual keyboard has changed. The evt.detail.boundingRect property is the new bounding rectangle of the virtual keyboard. Listen for this event on window.mathVirtualKeyboard
blur	The mathfield is losing focus
focus	The mathfield is gaining focus
move-out	The user has pressed an arrow key or the tab key, but there is nowhere to go. This is an opportunity to change the focus to another element if desired. `detail: {direction: 'forward'
keypress	The user pressed a physical keyboard key
mount	The element has been attached to the DOM
unmount	The element is about to be removed from the DOM

Extends

• HTMLElement

new MathfieldElement()

new MathfieldElement(options?): MathfieldElement

To create programmatically a new mathfield use:

let mfe = new MathfieldElement();

// Set initial value and options
mfe.value = "\\frac{\\sin(x)}{\\cos(x)}";

// Options can be set either as an attribute (for simple options)...
mfe.setAttribute("letter-shape-style", "french");

// ... or using properties
mfe.letterShapeStyle = "french";

// Attach the element to the DOM
document.body.appendChild(mfe);

options?

Partial<MathfieldOptions>

Accessing and changing the content

MathfieldElement.errors

Return an array of LaTeX syntax errors, if any.

MathfieldElement.expression

get expression(): any
set expression(mathJson: any): void

If the Compute Engine library is available, return a boxed MathJSON expression representing the value of the mathfield.

To load the Compute Engine library, use:

import 'https://unpkg.com/@cortex-js/compute-engine?module';

MathfieldElement.value

get value(): string
set value(value: string): void

The content of the mathfield as a LaTeX expression.

document.querySelector('mf').value = '\\frac{1}{\\pi}'

MathfieldElement.getValue()

getValue(format)

getValue(format?): string

Return a textual representation of the content of the mathfield.

format?

OutputFormat

The format of the result. If using math-json the Compute Engine library must be loaded, for example with:

import "https://unpkg.com/@cortex-js/compute-engine?module";

Default: "latex"

getValue(start, end, format)

getValue(start, end, format?): string

Return the value of the mathfield from start to end

start

number

end

number

format?

OutputFormat

getValue(range, format)

getValue(range, format?): string

Return the value of the mathfield in range

range

Range

format?

OutputFormat

MathfieldElement.insert()

insert(s, options?): boolean

Insert a block of text at the current insertion point.

This method can be called explicitly or invoked as a selector with executeCommand("insert").

After the insertion, the selection will be set according to the options.selectionMode.

s

string

options?

InsertOptions

MathfieldElement.setValue()

setValue(value?, options?): void

Set the content of the mathfield to the text interpreted as a LaTeX expression.

value?

string

options?

InsertOptions

Selection

MathfieldElement.lastOffset

The last valid offset.

MathfieldElement.position

get position(): number
set position(offset: number): void

The position of the caret/insertion point, from 0 to lastOffset.

MathfieldElement.selection

get selection(): Readonly<Selection>
set selection(sel: number | Selection): void

An array of ranges representing the selection.

It is guaranteed there will be at least one element. If a discontinuous selection is present, the result will include more than one element.

MathfieldElement.selectionIsCollapsed

MathfieldElement.getOffsetFromPoint()

getOffsetFromPoint(x, y, options?): number

The offset closest to the location (x, y) in viewport coordinate.

bias: if 0, the vertical midline is considered to the left or right sibling. If -1, the left sibling is favored, if +1, the right sibling is favored.

x

number

y

number

options?

bias?

-1 | 0 | 1

MathfieldElement.select()

select(): void

Select the content of the mathfield.

Customization

MathfieldElement.restoreFocusWhenDocumentFocused

static restoreFocusWhenDocumentFocused: boolean = true;

When switching from a tab to one that contains a mathfield that was previously focused, restore the focus to the mathfield.

This is behavior consistent with <textarea>, however it can be disabled if it is not desired.

Default: true

MathfieldElement.backgroundColorMap

get backgroundColorMap(): (name) => string
set backgroundColorMap(value: (name) => string): void

MathfieldElement.colorMap

get colorMap(): (name) => string
set colorMap(value: (name) => string): void

Map a color name as used in commands such as \textcolor{}{} or \colorbox{}{} to a CSS color value.

Use this option to override the standard mapping of colors such as "yellow" or "red".

If the name is not one you expected, return undefined and the default color mapping will be applied.

If a backgroundColorMap() function is not provided, the colorMap() function will be used instead.

If colorMap() is not provided, default color mappings are applied.

The following color names have been optimized for a legible foreground and background values, and are recommended:

• red, orange, yellow, lime, green, teal, blue, indigo, purple, magenta, black, dark-grey, grey, light-grey, white

MathfieldElement.defaultMode

get defaultMode(): "text" | "math" | "inline-math"
set defaultMode(value: "text" | "math" | "inline-math"): void

The mode of the element when it is empty:

• "math": equivalent to \displaystyle (display math mode)
• "inline-math": equivalent to \inlinestyle (inline math mode)
• "text": text mode

MathfieldElement.environmentPopoverPolicy

get environmentPopoverPolicy(): "auto" | "off" | "on"
set environmentPopoverPolicy(value: "auto" | "off" | "on"): void

If "auto" a popover with commands to edit an environment (matrix) is displayed when the virtual keyboard is displayed.

Default: "auto"

MathfieldElement.letterShapeStyle

get letterShapeStyle(): "auto" | "tex" | "iso" | "french" | "upright"
set letterShapeStyle(value: "auto" | "tex" | "iso" | "french" | "upright"): void

Control the letter shape style:

letterShapeStyle	xyz	ABC	αβɣ	ΓΔΘ
iso	it	it	it	it
tex	it	it	it	up
french	it	up	up	up
upright	up	up	up	up

(it) = italic (up) = upright

The default letter shape style is auto, which indicates that french should be used if the locale is "french", and tex otherwise.

Historical Note

Where do the "french" rules come from? The TeX standard font, Computer Modern, is based on Monotype 155M, itself based on the Porson greek font which was one of the most widely used Greek fonts in english-speaking countries. This font had upright capitals, but slanted lowercase. In France, the traditional font for greek was Didot, which has both upright capitals and lowercase.

As for roman uppercase, they are recommended by "Lexique des règles typographiques en usage à l’Imprimerie Nationale". It should be noted that this convention is not universally followed.

MathfieldElement.mathModeSpace

get mathModeSpace(): string
set mathModeSpace(value: string): void

The LaTeX string to insert when the spacebar is pressed (on the physical or virtual keyboard).

Use "\;" for a thick space, "\:" for a medium space, "\," for a thin space.

Do not use " " (a regular space), as whitespace is skipped by LaTeX so this will do nothing.

Default: "" (empty string)

MathfieldElement.maxMatrixCols

get maxMatrixCols(): number
set maxMatrixCols(value: number): void

Sets the maximum number of columns for the matrix environment. The default is 10 columns to match the behavior of the amsmath matrix environment. Default: 10

MathfieldElement.minFontScale

get minFontScale(): number
set minFontScale(value: number): void

Set the minimum relative font size for nested superscripts and fractions. The value should be a number between 0 and 1. The size is in releative em units relative to the font size of the math-field element. Specifying a value of 0 allows the math-field to use its default sizing logic.

Default: 0

MathfieldElement.placeholder

get placeholder(): string
set placeholder(value: string): void

A LaTeX string displayed inside the mathfield when there is no content.

MathfieldElement.placeholderSymbol

get placeholderSymbol(): string
set placeholderSymbol(value: string): void

The symbol used to represent a placeholder in an expression.

Default: ▢ U+25A2 WHITE SQUARE WITH ROUNDED CORNERS

MathfieldElement.popoverPolicy

get popoverPolicy(): "auto" | "off"
set popoverPolicy(value: "auto" | "off"): void

If "auto" a popover with suggestions may be displayed when a LaTeX command is input.

Default: "auto"

MathfieldElement.removeExtraneousParentheses

get removeExtraneousParentheses(): boolean
set removeExtraneousParentheses(value: boolean): void

If true, extra parentheses around a numerator or denominator are removed automatically.

Default: true

MathfieldElement.scriptDepth

get scriptDepth(): number | [number, number]
set scriptDepth(value: number | [number, number]): void

This option controls how many levels of subscript/superscript can be entered. For example, if scriptDepth is "1", there can be one level of superscript or subscript. Attempting to enter a superscript while inside a superscript will be rejected. Setting a value of 0 will prevent entry of any superscript or subscript (but not limits for sum, integrals, etc...)

This can make it easier to enter equations that fit what's expected for the domain where the mathfield is used.

To control the depth of superscript and subscript independently, provide an array: the first element indicate the maximum depth for subscript and the second element the depth of superscript. Thus, a value of [0, 1] would suppress the entry of subscripts, and allow one level of superscripts.

MathfieldElement.smartFence

get smartFence(): boolean
set smartFence(value: boolean): void

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.

MathfieldElement.smartMode

get smartMode(): boolean
set smartMode(value: boolean): void

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

Default: false

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

MathfieldElement.smartSuperscript

get smartSuperscript(): boolean
set smartSuperscript(value: boolean): void

When true and 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.

Styles

MathfieldElement.onInsertStyle

get onInsertStyle(): InsertStyleHook
set onInsertStyle(value: InsertStyleHook): void

MathfieldElement.applyStyle()

applyStyle(style, options?): void

Update the style (color, bold, italic, etc...) of the selection or sets the style to be applied to future input.

If there is no selection and no range is specified, the style will apply to the next character typed.

If a range is specified, the style is applied to the range, otherwise, if there is a selection, the style is applied to the selection.

If the operation is "toggle" and the range already has this style, remove it. If the range has the style partially applied (i.e. only some sections), remove it from those sections, and apply it to the entire range.

If the operation is "set", the style is applied to the range, whether it already has the style or not.

The default operation is "set".

style

Readonly<Style>

options?

Range | { operation: "set" | "toggle"; range: Range; }

MathfieldElement.queryStyle()

queryStyle(style): "some" | "all" | "none"

If there is a selection, return if all the atoms in the selection, some of them or none of them match the style argument.

If there is no selection, return 'all' if the current implicit style (determined by a combination of the style of the previous atom and the current style) matches the style argument, 'none' if it does not.

style

Readonly<Style>

Macros

MathfieldElement.macros

get macros(): Readonly<MacroDictionary>
set macros(value: MacroDictionary): void

A dictionary of LaTeX macros to be used to interpret and render the content.

For example, to add a new macro to the default macro dictionary:

mf.macros = {
...mf.macros,
smallfrac: '^{#1}\\!\\!/\\!_{#2}',
};

Note that ...mf.macros is used to keep the existing macros and add to them. Otherwise, all the macros are replaced with the new definition.

The code above will support the following notation:

\smallfrac{5}{16}

Registers

MathfieldElement.registers

get registers(): Registers
set registers(value: Registers): void

TeX registers represent "variables" and "constants".

Changing the values of some registers can modify the layout of math expressions.

The following registers might be of interest:

• thinmuskip: space between items of math lists
• medmuskip: space between binary operations
• thickmuskip: space between relational operators
• nulldelimiterspace: minimum space to leave blank in delimiter constructions, for example around a fraction
• delimitershortfall: maximum space to overlap adjacent elements when a delimiter is too short
• jot: space between lines in an array, or between rows in a multiline construct
• arraycolsep: space between columns in an array
• arraystretch: factor by which to stretch the height of each row in an array

To modify a register, use:

mf.registers.arraystretch = 1.5;
mf.registers.thinmuskip = { dimension: 2, unit: "mu" };
mf.registers.medmuskip = "3mu";

Speech

MathfieldElement.readAloudHook()

static readAloudHook: (element, text) => void = defaultReadAloudHook;

MathfieldElement.speakHook()

static speakHook: (text) => void = defaultSpeakHook;

MathfieldElement.speechEngine

get static speechEngine(): "amazon" | "local"
set static speechEngine(value: "amazon" | "local"): void

Indicates which speech engine to use for speech output.

Use local to use the OS-specific TTS engine.

Use amazon for Amazon Text-to-Speech cloud API. You must include the AWS API library and configure it with your API key before use.

See mathfield/guides/speech/ | Guide: Speech

MathfieldElement.speechEngineRate

get static speechEngineRate(): string
set static speechEngineRate(value: string): void

Sets the speed of the selected voice.

One of x-slow, slow, medium, fast, x-fast or a value as a percentage.

Range is 20% to 200% For example 200% to indicate a speaking rate twice the default rate.

MathfieldElement.speechEngineVoice

get static speechEngineVoice(): string
set static speechEngineVoice(value: string): void

Indicates the voice to use with the speech engine.

This is dependent on the speech engine. For Amazon Polly, see here: https://docs.aws.amazon.com/polly/latest/dg/voicelist.html

MathfieldElement.textToSpeechMarkup

get static textToSpeechMarkup(): "" | "ssml" | "ssml_step" | "mac"
set static textToSpeechMarkup(value: "" | "ssml" | "ssml_step" | "mac"): void

The markup syntax to use for the output of conversion to spoken text.

Possible values are ssml for the SSML markup or mac for the macOS markup, i.e. [[ltr]].

MathfieldElement.textToSpeechRules

get static textToSpeechRules(): "sre" | "mathlive"
set static textToSpeechRules(value: "sre" | "mathlive"): void

Specify which set of text to speech rules to use.

A value of mathlive indicates that the simple rules built into MathLive should be used.

A value of sre indicates that the Speech Rule Engine from Volker Sorge should be used.

(Caution) SRE is not included or loaded by MathLive. For this option to work SRE should be loaded separately.

See mathfield/guides/speech/ | Guide: Speech

MathfieldElement.textToSpeechRulesOptions

get static textToSpeechRulesOptions(): Readonly<Record<string, string>>
set static textToSpeechRulesOptions(value: Record<string, string>): void

A set of key/value pairs that can be used to configure the speech rule engine.

Which options are available depends on the speech rule engine in use. There are no options available with MathLive's built-in engine. The options for the SRE engine are documented here

Focus

MathfieldElement.blur()

blur(): void

Remove the focus from the mathfield (will no longer respond to keyboard input).

MathfieldElement.focus()

focus(): void

Sets the focus to the mathfield (will respond to keyboard input).

MathfieldElement.hasFocus()

hasFocus(): boolean

Return true if the mathfield is currently focused (responds to keyboard input).

Prompts

MathfieldElement.getPromptRange()

getPromptRange(id): Range

Return the selection range for the specified prompt.

This can be used for example to select the content of the prompt.

mf.selection = mf.getPromptRange('my-prompt-id');

id

string

MathfieldElement.getPrompts()

getPrompts(filter?): string[]

Return the id of the prompts matching the filter.

filter?

correctness?

"undefined" | "correct" | "incorrect"

id?

string

locked?

boolean

MathfieldElement.getPromptState()

getPromptState(id): ["correct" | "incorrect", boolean]

id

string

MathfieldElement.getPromptValue()

getPromptValue(placeholderId, format?): string

Return the content of the \placeholder{} command with the placeholderId

placeholderId

string

format?

OutputFormat

MathfieldElement.setPromptState()

setPromptState(id, state, locked?): void

id

string

state

"undefined" | "correct" | "incorrect"

locked?

boolean

MathfieldElement.setPromptValue()

setPromptValue(id, content, insertOptions): void

id

string

content

string

insertOptions

Omit<InsertOptions, "insertionMode">

Undo

MathfieldElement.canRedo()

canRedo(): boolean

Return whether there are redoable items

MathfieldElement.canUndo()

canUndo(): boolean

Return whether there are undoable items

MathfieldElement.resetUndo()

resetUndo(): void

Reset the undo stack

Keyboard Shortcuts

MathfieldElement.inlineShortcuts

get inlineShortcuts(): Readonly<InlineShortcutDefinitions>
set inlineShortcuts(value: InlineShortcutDefinitions): void

The keys of this object literal indicate the sequence of characters that will trigger an inline shortcut.

MathfieldElement.inlineShortcutTimeout

get inlineShortcutTimeout(): number
set inlineShortcutTimeout(value: number): void

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.

MathfieldElement.keybindings

get keybindings(): readonly Keybinding[]
set keybindings(value: readonly Keybinding[]): void

Menu

MathfieldElement.menuItems

get menuItems(): readonly MenuItem[]
set menuItems(menuItems: readonly MenuItem[]): void

MathfieldElement.showMenu()

showMenu(_): boolean

_

location

{ x: number; y: number; }

location.x

number

location.y

number

modifiers

KeyboardModifiers

Virtual Keyboard

MathfieldElement.keypressVibration

static keypressVibration: boolean = true;

When a key on the virtual keyboard is pressed, produce a short haptic feedback, if the device supports it.

MathfieldElement.mathVirtualKeyboardPolicy

get mathVirtualKeyboardPolicy(): VirtualKeyboardPolicy
set mathVirtualKeyboardPolicy(value: VirtualKeyboardPolicy): void

MathfieldElement.virtualKeyboardTargetOrigin

get virtualKeyboardTargetOrigin(): string
set virtualKeyboardTargetOrigin(value: string): void

MathfieldElement.keypressSound

get static keypressSound(): Readonly<{
  default: string;
  delete: string;
  return: string;
  spacebar: string;
}>
set static keypressSound(value: 
  | string
  | {
  default: string;
  delete: string;
  return: string;
  spacebar: string;
 }): void

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

If the property is set to a string, the same sound is played in all cases. Otherwise, a distinct sound is played:

• delete a sound played when the delete key is pressed
• return ... when the return/tab key is pressed
• spacebar ... when the spacebar is pressed
• default ... when any other key is pressed. This property is required, the others are optional. If they are missing, this sound is played as well.

The value of the properties should be either a string, the name of an audio file in the soundsDirectory directory or null to suppress the sound.

If the soundsDirectory is null, no sound will be played.

MathfieldElement.soundsDirectory

get static soundsDirectory(): string
set static soundsDirectory(value: string): void

A URL fragment pointing to the directory containing the optional sounds used to provide feedback while typing.

Some default sounds are available in the /dist/sounds directory of the SDK.

Use null to prevent any sound from being loaded.

Localization

MathfieldElement.decimalSeparator

get static decimalSeparator(): "," | "."
set static decimalSeparator(value: "," | "."): void

The symbol used to separate the integer part from the fractional part of a number.

When "," is used, the corresponding LaTeX string is {,}, in order to ensure proper spacing (otherwise an extra gap is displayed after the comma).

This affects:

• what happens when the , key is pressed (if decimalSeparator is ",", the {,} LaTeX string is inserted when following some digits)
• the label and behavior of the "." key in the default virtual keyboard

Default: "."

MathfieldElement.fractionNavigationOrder

get static fractionNavigationOrder(): "denominator-numerator" | "numerator-denominator"
set static fractionNavigationOrder(s: "denominator-numerator" | "numerator-denominator"): void

When using the keyboard to navigate a fraction, the order in which the numerator and navigator are traversed:

• "numerator-denominator": first the elements in the numerator, then the elements in the denominator.
• "denominator-numerator": first the elements in the denominator, then the elements in the numerator. In some East-Asian cultures, fractions are read and written denominator first ("fēnzhī"). With this option the keyboard navigation follows this convention.

Default: "numerator-denominator"

MathfieldElement.locale

get static locale(): string
set static locale(value: string): void

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

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

MathfieldElement.strings

get static strings(): Readonly<Record<string, Record<string, string>>>
set static strings(value: Record<string, Record<string, string>>): void

An object whose keys are a locale string, and whose values are an object of string identifier to localized string.

Example

mf.strings = {
  "fr-CA": {
      "tooltip.undo": "Annuler",
      "tooltip.redo": "Refaire",
  }
}

If the locale is already supported, this will override the existing strings. If the locale is not supported, it will be added.

Other

MathfieldElement.createHTML()

static createHTML: (html) => any;

Support for Trusted Type.

This optional function will be called before a string of HTML is injected in the DOM, allowing that string to be sanitized according to a policy defined by the host.

Consider using this option if you are displaying untrusted content. Read more about Security Considerations

MathfieldElement.version

static version: string = '{{SDK_VERSION}}';

MathfieldElement.disabled

get disabled(): boolean
set disabled(value: boolean): void

MathfieldElement.mode

get mode(): ParseMode
set mode(value: ParseMode): void

MathfieldElement.readonly

get readonly(): boolean
set readonly(value: boolean): void

MathfieldElement.readOnly

get readOnly(): boolean
set readOnly(value: boolean): void

MathfieldElement.computeEngine

get static computeEngine(): ComputeEngine
set static computeEngine(value: ComputeEngine): void

A custom compute engine instance. If none is provided, a default one is used. If null is specified, no compute engine is used.

MathfieldElement.fontsDirectory

get static fontsDirectory(): string
set static fontsDirectory(value: string): void

A URL fragment pointing to the directory containing the fonts necessary to render a formula.

These fonts are available in the /dist/fonts directory of the SDK.

Customize this value to reflect where you have copied these fonts, or to use the CDN version.

The default value is "./fonts". Use null to prevent any fonts from being loaded.

Changing this setting after the mathfield has been created will have no effect.

{
     // Use the CDN version
     fontsDirectory: ''
}

{
     // Use a directory called "fonts", located next to the
     // `mathlive.js` (or `mathlive.mjs`) file.
     fontsDirectory: './fonts'
}

{
     // Use a directory located at the root of your website
     fontsDirectory: 'https://example.com/fonts'
}

MathfieldElement.isFunction

get static isFunction(): (command) => boolean
set static isFunction(value: (command) => boolean): void

MathfieldElement.plonkSound

get static plonkSound(): string
set static plonkSound(value: string): void

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
• null to turn off the sound

If the soundsDirectory is null, no sound will be played.

MathfieldElement.getElementInfo()

getElementInfo(offset): ElementInfo

offset

number

MathfieldElement.loadSound()

static loadSound(sound): Promise<void>

sound

"keypress" | "plonk" | "delete" | "spacebar" | "return"

MathfieldElement.openUrl()

static openUrl(href): void

href

string

MathfieldElement.playSound()

static playSound(name): Promise<void>

name

"keypress" | "plonk" | "delete" | "spacebar" | "return"

Commands

MathfieldElement.executeCommand()

executeCommand(selector)

executeCommand(selector): boolean

Execute a command defined by a selector.

mfe.executeCommand('add-column-after');
mfe.executeCommand(['switch-mode', 'math']);

selector

Selector

A selector, or an array whose first element is a selector, and whose subsequent elements are arguments to the selector.

Selectors can be passed either in camelCase or kebab-case.

// Both calls do the same thing
mfe.executeCommand('selectAll');
mfe.executeCommand('select-all');

executeCommand(selector, args)

executeCommand(selector, ...args): boolean

Execute a command defined by a selector.

mfe.executeCommand('add-column-after');
mfe.executeCommand(['switch-mode', 'math']);

selector

Selector

A selector, or an array whose first element is a selector, and whose subsequent elements are arguments to the selector.

Selectors can be passed either in camelCase or kebab-case.

// Both calls do the same thing
mfe.executeCommand('selectAll');
mfe.executeCommand('select-all');

args

...unknown[]

executeCommand(selector)

executeCommand(selector): boolean

Execute a command defined by a selector.

mfe.executeCommand('add-column-after');
mfe.executeCommand(['switch-mode', 'math']);

selector

[Selector, ...unknown[]]

A selector, or an array whose first element is a selector, and whose subsequent elements are arguments to the selector.

Selectors can be passed either in camelCase or kebab-case.

// Both calls do the same thing
mfe.executeCommand('selectAll');
mfe.executeCommand('select-all');

Hooks

MathfieldElement.onExport

get onExport(): (from, latex, range) => string
set onExport(value: (from, latex, range) => string): void

This hook 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*}`;

MathfieldElement.onInlineShortcut

get onInlineShortcut(): (sender, symbol) => string
set onInlineShortcut(value: (sender, symbol) => string): void

A hook invoked when a string of characters that could be interpreted as shortcut has been typed.

If not a special shortcut, return the empty string "".

Use this handler to detect multi character symbols, and return them wrapped appropriately, for example \mathrm{${symbol}}.

MathfieldElement.onScrollIntoView

get onScrollIntoView(): (sender) => void
set onScrollIntoView(value: (sender) => void): void

A hook invoked when scrolling the mathfield into view is necessary.

Use when scrolling the page would not solve the problem, e.g. when the mathfield is in another div that has scrollable content.

MathfieldElementAttributes

These attributes of the <math-field> element correspond to matching properties.

Indexable

[key: string]: unknown

MathfieldElementAttributes.default-mode

default-mode: string;

MathfieldElementAttributes.inline-shortcut-timeout

inline-shortcut-timeout: string;

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.

MathfieldElementAttributes.letter-shape-style

letter-shape-style: string;

MathfieldElementAttributes.math-mode-space

math-mode-space: string;

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.

MathfieldElementAttributes.math-virtual-keyboard-policy

math-virtual-keyboard-policy: VirtualKeyboardPolicy;

• "auto": the virtual keyboard is triggered when a mathfield is focused on a touch capable device.
• "manual": the virtual keyboard is not triggered automatically
• "sandboxed": the virtual keyboard is displayed in the current browsing context (iframe) if it has a defined container or is the top-level browsing context.

MathfieldElementAttributes.max-matrix-cols

max-matrix-cols: number;

MathfieldElementAttributes.min-font-scale

min-font-scale: number;

MathfieldElementAttributes.placeholder

placeholder: string;

When the mathfield is empty, display this placeholder LaTeX string instead

MathfieldElementAttributes.popover-policy

popover-policy: string;

MathfieldElementAttributes.read-only

read-only: boolean;

When true, the user cannot edit the mathfield.

MathfieldElementAttributes.remove-extraneous-parentheses

remove-extraneous-parentheses: boolean;

MathfieldElementAttributes.script-depth

script-depth: string;

MathfieldElementAttributes.smart-fence

smart-fence: string;

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

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

MathfieldElementAttributes.smart-mode

smart-mode: string;

When on, 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^&#007b;2n+1&#007d;<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 &#007b;(x,y)|0<=x<=1 and 0<=y<=x&#007d;
• \int_&#007b;the unit square&#007d; f(x,y) dx dy
• For all n in NN

MathfieldElementAttributes.smart-superscript

smart-superscript: string;

When on, 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 off, the navigation out of the superscript must always be done manually.

MathfieldElementAttributes.virtual-keyboard-target-origin

virtual-keyboard-target-origin: string;

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

Default: window.origin

ElementInfo

type ElementInfo = {
  bounds: DOMRect;
  data: Record<string, string | undefined>;
  depth: number;
  id: string;
  latex: string;
  mode: ParseMode;
  style: Style;
};

Some additional information about an element of the formula returned by mf.getElementInfo().

ElementInfo.bounds?

optional bounds: DOMRect;

The bounding box of the element

ElementInfo.data?

optional data: Record<string, string | undefined>;

HTML attributes associated with element or its ancestores, set with \htmlData

ElementInfo.depth?

optional depth: number;

The depth in the expression tree. 0 for top-level elements

ElementInfo.id?

optional id: string;

id associated with this element or its ancestor, set with \htmlId or \cssId

ElementInfo.latex?

optional latex: string;

A LaTeX representation of the element

ElementInfo.mode?

optional mode: ParseMode;

The mode (math, text or LaTeX)

ElementInfo.style?

optional style: Style;

The style (color, weight, variant, etc...) of this element.

InsertOptions

type InsertOptions = {
  feedback: boolean;
  focus: boolean;
  format: OutputFormat | "auto";
  insertionMode: "replaceSelection" | "replaceAll" | "insertBefore" | "insertAfter";
  mode: ParseMode | "auto";
  scrollIntoView: boolean;
  selectionMode: "placeholder" | "after" | "before" | "item";
  silenceNotifications: boolean;
  style: Style;
};

InsertOptions.feedback?

optional feedback: boolean;

If true, provide audio and haptic feedback

InsertOptions.focus?

optional focus: boolean;

If true, the mathfield will be focused after the insertion

InsertOptions.format?

optional format: OutputFormat | "auto";

The format of the input string:

"auto"	The string is LaTeX fragment or command) (default)
"latex"	The string is a LaTeX fragment

InsertOptions.mode?

optional mode: ParseMode | "auto";

If "auto" or omitted, the current mode is used

InsertOptions.scrollIntoView?

optional scrollIntoView: boolean;

If true, scroll the mathfield into view after insertion such that the insertion point is visible

InsertOptions.selectionMode?

optional selectionMode: "placeholder" | "after" | "before" | "item";

Describes where the selection will be after the insertion:

"placeholder"	The selection will be the first available placeholder in the text that has been inserted (default)
"after"	The selection will be an insertion point after the inserted text
"before"	The selection will be an insertion point before the inserted text
"item"	The inserted text will be selected

MoveOutEvent

type MoveOutEvent = {
  direction: "forward" | "backward" | "upward" | "downward";
};

Event re-targeting

Some events bubble up through the DOM tree, so that they are detectable by any element on the page.

Bubbling events fired from within shadow DOM are re-targeted so that, to any listener external to your component, they appear to come from your component itself.

Custom Event Bubbling

By default, a bubbling custom event fired inside shadow DOM will stop bubbling when it reaches the shadow root.

To make a custom event pass through shadow DOM boundaries, you must set both the composed and bubbles flags to true.

The move-out event signals that the user pressed an arrow key or tab 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.

OutputFormat

type OutputFormat = 
  | "ascii-math"
  | "latex"
  | "latex-expanded"
  | "latex-unstyled"
  | "latex-without-placeholders"
  | "math-json"
  | "math-ml"
  | "plain-text"
  | "spoken"
  | "spoken-text"
  | "spoken-ssml"
  | "spoken-ssml-with-highlighting";

Format	Description
"ascii-math"	A string of ASCIIMath.
"latex"	LaTeX rendering of the content, with LaTeX macros not expanded.
"latex-expanded"	All macros are recursively expanded to their definition.
"latex-unstyled"	Styling (background color, color) is ignored
"latex-without-placeholders"	Replace \placeholder commands with their body
"math-json"	A MathJSON abstract syntax tree, as an object literal formated as a JSON string. Note: you must import the CortexJS Compute Engine to obtain a result.
"math-ml"	A string of MathML markup.
"plain-text"	A plain text rendering of the content.
"spoken"	Spoken text rendering, using the default format defined in config, which could be either text or SSML markup.
"spoken-text"	A plain spoken text rendering of the content.
"spoken-ssml"	A SSML (Speech Synthesis Markup Language) version of the content, which can be used with some text-to-speech engines such as AWS.
"spoken-ssml-with-highlighting"	Like "spoken-ssml" but with additional annotations necessary for synchronized highlighting (read aloud).

To use the"math-json" format the Compute Engine library must be loaded. Use for example:

import "https://unpkg.com/@cortex-js/compute-engine?module";

Selection

Offset

type Offset = number;

Position of the caret/insertion point from the beginning of the formula. The first position is 0. The last valid offset is mf.lastOffset.

Range

type Range = [Offset, Offset];

A pair of offsets (boundary points) that can be used to denote a fragment of an expression.

A range is said to be collapsed when start and end are equal.

When specifying a range, a negative offset can be used to indicate an offset relative to the last valid offset, i.e. -1 is the last valid offset, -2 is one offset before that, etc...

A normalized range will always be such that start <= end, start >= 0, end >= 0, start < lastOffset, end < lastOffset. All the methods return a normalized range.

See Also

• Selection

Selection

type Selection = {
  direction: "forward" | "backward" | "none";
  ranges: Range[];
};

A selection is a set of ranges (to support discontinuous selection, for example when selecting a column in a matrix).

If there is a single range and that range is collapsed, the selection is collapsed.

A selection can also have a direction. While many operations are insensitive to the direction, a few are. For example, when selecting a fragment of an expression from left to right, the direction of this range will be "forward". Pressing the left arrow key will sets the insertion at the start of the range. Conversely, if the selection is made from right to left, the direction is "backward" and pressing the left arrow key will set the insertion point at the end of the range.

See Also

• Range

Styles

Style

Style.backgroundColor?

optional backgroundColor: string;

Style.color?

optional color: string;

Style.fontFamily?

optional fontFamily: FontFamily;

Style.fontSeries?

optional fontSeries: FontSeries;

Style.fontShape?

optional fontShape: FontShape;

Style.fontSize?

optional fontSize: "auto" | FontSize;

Style.variant?

optional variant: Variant;

Style.variantStyle?

optional variantStyle: VariantStyle;

ApplyStyleOptions

type ApplyStyleOptions = {
  operation: "set" | "toggle";
  range: Range;
  silenceNotifications: boolean;
};

FontFamily

type FontFamily = "none" | "roman" | "monospace" | "sans-serif";

FontSeries

type FontSeries = "auto" | "m" | "b" | "l" | "";

FontShape

type FontShape = "auto" | "n" | "it" | "sl" | "sc" | "";

FontSize

type FontSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;

InsertStyleHook()

type InsertStyleHook = (sender, at, info) => Readonly<Style>;

MathstyleName

type MathstyleName = "displaystyle" | "textstyle" | "scriptstyle" | "scriptscriptstyle";

Variant

type Variant = 
  | "ams"
  | "double-struck"
  | "calligraphic"
  | "script"
  | "fraktur"
  | "sans-serif"
  | "monospace"
  | "normal"
  | "main"
  | "math";

Variants indicate a stylistic alternate for some characters.

Typically, those are controlled with explicit commands, such as \mathbb{} or \mathfrak{}. This type is used with the MathfieldElement.applyStyle method to change the styling of a range of selected characters.

In mathematical notation these variants are used not only for visual presentation, but they may have semantic significance.

For example,

• the set ℂ should not be confused with
• the physical unit 𝖢 (Coulomb).

When rendered, these variants can map to some built-in fonts.

LaTeX supports a limited set of characters. However, MathLive will map characters not supported by LaTeX fonts (double-stuck variant for digits for example) to a Unicode character (see Mathematical Alphanumeric Symbols on Wikipedia ).

normal is a synthetic variant that maps either to main (upright) or math (italic) depending on the symbol and the letterShapeStyle.

The math variant has italic characters as well as slightly different letter shape and spacing (a bit more space after the "f" for example), so it's not equivalent to a main variant with italic variant style applied.

See Also

• Style

VariantStyle

type VariantStyle = "up" | "bold" | "italic" | "bolditalic" | "";

Some variants support stylistic variations.

Note that these stylistic variations support a limited set of characters, typically just uppercase and lowercase letters, and digits 0-9 in some cases.

variant	up	bold	italic	bolditalic
normal	ABCabc012	𝐀𝐁𝐂𝐚𝐛𝐜𝟎𝟏𝟐	𝐴𝐵𝐶𝑎𝑏𝑐	𝑨𝑩𝑪𝒂𝒃𝒄
double-struck	𝔸𝔹ℂ𝕒𝕓𝕔𝟘𝟙𝟚	n/a	n/a	n/a
calligraphic	𝒜ℬ𝒞𝒶𝒷𝒸	𝓐𝓑𝓒𝓪𝓫𝓬	n/a	n/a
fraktur	𝔄𝔅ℭ𝔞𝔟𝔠	𝕬𝕭𝕮𝖆𝖇𝖈	n/a	n/a
sans-serif	𝖠𝖡𝖢𝖺𝖻𝖼𝟢𝟣𝟤	𝗔𝗕𝗖𝗮𝗯𝗰𝟬𝟭𝟮	𝘈𝘉𝘊𝘢𝘣𝘤	𝘼𝘽𝘾𝙖𝙗𝙘
monospace	𝙰𝙱𝙲𝚊𝚋𝚌	n/a	n/a	n/a

Macros

MacroDefinition

type MacroDefinition = {
  args: number;
  captureSelection: boolean;
  def: string;
  expand: boolean;
};

See Also

• MacroDictionary
• Macros guide

MacroDefinition.args?

optional args: number;

Number of arguments (#1, etc...) in the macro definition

MacroDefinition.captureSelection?

optional captureSelection: boolean;

If false elements inside the macro can be selected

MacroDefinition.def

def: string;

Definition of the macro as a LaTeX expression

MacroDefinition.expand?

optional expand: boolean;

If false, even if expandMacro is true, do not expand.

MacroDictionary

type MacroDictionary = Record<string, 
  | string
  | Partial<MacroDefinition>
| MacroPackageDefinition>;

A dictionary of LaTeX macros to be used to interpret and render the content.

For example:

mf.macros = { smallfrac: "^{#1}\\!\\!/\\!_{#2}" };

The code above will support the following notation:

\smallfrac{5}{16}

See Also

• Macros Example

MacroPackageDefinition

type MacroPackageDefinition = {
  captureSelection: boolean;
  package: Record<string, string | MacroDefinition>;
  primitive: boolean;
};

NormalizedMacroDictionary

type NormalizedMacroDictionary = Record<string, MacroDefinition>;

Registers

Dimension

type Dimension = {
  dimension: number;
  unit: DimensionUnit;
};

A dimension is used to specify the size of things

DimensionUnit

type DimensionUnit = 
  | "pt"
  | "mm"
  | "cm"
  | "ex"
  | "px"
  | "em"
  | "bp"
  | "dd"
  | "pc"
  | "in"
  | "mu"
  | "fil"
  | "fill"
  | "filll";

Glue

type Glue = {
  glue: Dimension;
  grow: Dimension;
  shrink: Dimension;
};

Glue represents flexible spacing, that is a dimension that can grow (by the grow property) or shrink (by the shrink property).

LatexValue

type LatexValue = {
  relax: boolean;
 } & 
  | Dimension
  | Glue
  | {
  string: string;
 }
  | {
  base: "decimal" | "octal" | "hexadecimal" | "alpha";
  number: number;
 }
  | {
  factor: number;
  global: boolean;
  register: string;
};

A LaTeX expression represent a sequence of tokens that can be evaluated to a value, such as a dimension.

Registers

type Registers = Record<string, number | string | LatexValue>;

TeX registers represent "variables" and "constants".

Changing the values of some registers can modify the layout of math expressions.

The following registers might be of interest:

• thinmuskip: space between items of math lists
• medmuskip: space between binary operations
• thickmuskip: space between relational operators
• nulldelimiterspace: minimum space to leave blank in delimiter constructions, for example around a fraction
• delimitershortfall: maximum space to overlap adjacent elements when a delimiter is too short
• jot: space between lines in an array, or between rows in a multiline construct
• arraycolsep: space between columns in an array
• arraystretch: factor by which to stretch the height of each row in an array

To modify a register, use:

mf.registers.arraystretch = 1.5;
mf.registers.thinmuskip = { dimension: 2, unit: "mu" };
mf.registers.medmuskip = "3mu";

Editing Commands

Commands

To perform editing commands on a mathfield, use MathfieldElement.executeCommand with the commands below.

const mf = document.getElementById('mathfield');
mf.executeCommand('selectAll');
mf.executeCommand('copyToClipboard');

Some commands require an argument, for example to insert a character:

mf.executeCommand('insert("x")' });

The argument can be specified in parentheses after the command name, or using an array:

mf.executeCommand(['switchMode', 'latex']);
// Same as mf.executeCommand('switchMode("latex")');

Commands (and executeCommand()) return true if they resulted in a dirty state.

Selection

Commands.extendSelectionBackward()

extendSelectionBackward: (model) => boolean;

Commands.extendSelectionDownward()

extendSelectionDownward: (model) => boolean;

Commands.extendSelectionForward()

extendSelectionForward: (model) => boolean;

Commands.extendSelectionUpward()

extendSelectionUpward: (model) => boolean;

Commands.extendToGroupEnd()

extendToGroupEnd: (model) => boolean;

Commands.extendToGroupStart()

extendToGroupStart: (model) => boolean;

Commands.extendToMathFieldEnd()

extendToMathFieldEnd: (model) => boolean;

Commands.extendToMathFieldStart()

extendToMathFieldStart: (model) => boolean;

Commands.extendToNextBoundary()

extendToNextBoundary: (model) => boolean;

Commands.extendToNextWord()

extendToNextWord: (model) => boolean;

Commands.extendToPreviousBoundary()

extendToPreviousBoundary: (model) => boolean;

Commands.extendToPreviousWord()

extendToPreviousWord: (model) => boolean;

Commands.moveAfterParent()

moveAfterParent: (model) => boolean;

Commands.moveBeforeParent()

moveBeforeParent: (model) => boolean;

Commands.moveDown()

moveDown: (model) => boolean;

Commands.moveToGroupEnd()

moveToGroupEnd: (model) => boolean;

Commands.moveToGroupStart()

moveToGroupStart: (model) => boolean;

Commands.moveToMathfieldEnd()

moveToMathfieldEnd: (model) => boolean;

Commands.moveToMathfieldStart()

moveToMathfieldStart: (model) => boolean;

Commands.moveToNextChar()

moveToNextChar: (model) => boolean;

Commands.moveToNextGroup()

moveToNextGroup: (model) => boolean;

Commands.moveToNextPlaceholder()

moveToNextPlaceholder: (model) => boolean;

Commands.moveToNextWord()

moveToNextWord: (model) => boolean;

Commands.moveToOpposite()

moveToOpposite: (model) => boolean;

Commands.moveToPreviousChar()

moveToPreviousChar: (model) => boolean;

Commands.moveToPreviousGroup()

moveToPreviousGroup: (model) => boolean;

Commands.moveToPreviousPlaceholder()

moveToPreviousPlaceholder: (model) => boolean;

Commands.moveToPreviousWord()

moveToPreviousWord: (model) => boolean;

Commands.moveToSubscript()

moveToSubscript: (model) => boolean;

Commands.moveToSuperscript()

moveToSuperscript: (model) => boolean;

Commands.moveUp()

moveUp: (model) => boolean;

Commands.selectAll()

selectAll: (model) => boolean;

Commands.selectGroup()

selectGroup: (model) => boolean;

Other

Commands.applyStyle()

applyStyle: (mathfield, style) => boolean;

Commands.commit()

commit: (mathfield) => boolean;

Commands.dispatchEvent()

dispatchEvent: (mathfield, name, detail) => boolean;

Dispatch a custom event on the host (mathfield)

Commands.insert()

insert: (mathfield, s, options) => boolean;

Commands.insertDecimalSeparator()

insertDecimalSeparator: (mathfield) => boolean;

Commands.performWithFeedback()

performWithFeedback: (mathfield, command) => boolean;

Perform a command and include interactive feedback such as sound and haptic feedback.

This is useful to simulate user interaction, for example for commands from the virtual keyboard

Commands.plonk()

plonk: (mathfield) => boolean;

Commands.speak()

speak: (mathfield, scope, options) => boolean;

mathfield

Mathfield

scope

SpeechScope

How much of the formula should be spoken:

all	the entire formula
selection	the selection portion of the formula
left	the element to the left of the selection
right	the element to the right of the selection
group	the group (numerator, root, etc..) the selection is in
parent	the parent of the selection

options

withHighlighting

boolean

In addition to speaking the requested portion of the formula, visually highlight it as it is read (read aloud functionality)

Commands.switchMode()

switchMode: (mathfield, mode) => boolean;

Commands.toggleContextMenu()

toggleContextMenu: (mathfield) => boolean;

Commands.toggleKeystrokeCaption()

toggleKeystrokeCaption: (mathfield) => boolean;

Commands.typedText()

typedText: (text, options) => boolean;

Array

Commands.addColumnAfter()

addColumnAfter: (model) => boolean;

Commands.addColumnBefore()

addColumnBefore: (model) => boolean;

Commands.addRowAfter()

addRowAfter: (model) => boolean;

Commands.addRowBefore()

addRowBefore: (model) => boolean;

Commands.removeColumn()

removeColumn: (model) => boolean;

Commands.removeRow()

removeRow: (model) => boolean;

Commands.setEnvironment()

setEnvironment: (model, environment) => boolean;

Auto-complete

Commands.complete()

complete: (mathfield) => boolean;

Commands.nextSuggestion()

nextSuggestion: (mathfield) => boolean;

Commands.previousSuggestion()

previousSuggestion: (mathfield) => boolean;

Clipboard

Commands.copyToClipboard()

copyToClipboard: (mathfield) => boolean;

Commands.cutToClipboard()

cutToClipboard: (mathfield) => boolean;

Commands.pasteFromClipboard()

pasteFromClipboard: (mathfield) => boolean;

Deleting

Commands.deleteAll()

deleteAll: (model) => boolean;

Commands.deleteBackward()

deleteBackward: (model) => boolean;

Commands.deleteForward()

deleteForward: (model) => boolean;

Commands.deleteNextWord()

deleteNextWord: (model) => boolean;

Commands.deletePreviousWord()

deletePreviousWord: (model) => boolean;

Commands.deleteToGroupEnd()

deleteToGroupEnd: (model) => boolean;

Commands.deleteToGroupStart()

deleteToGroupStart: (model) => boolean;

Commands.deleteToMathFieldEnd()

deleteToMathFieldEnd: (model) => boolean;

Commands.deleteToMathFieldStart()

deleteToMathFieldStart: (model) => boolean;

Prompt

Commands.insertPrompt()

insertPrompt: (mathfield, id?, options?) => boolean;

Scrolling

Commands.scrollIntoView()

scrollIntoView: (mathfield) => boolean;

Commands.scrollToEnd()

scrollToEnd: (mathfield) => boolean;

Commands.scrollToStart()

scrollToStart: (mathfield) => boolean;

Undo/Redo

Commands.redo()

redo: (mathfield) => boolean;

Commands.undo()

undo: (mathfield) => boolean;

VirtualKeyboardCommands

VirtualKeyboardCommands.hideVirtualKeyboard()

hideVirtualKeyboard: () => boolean;

VirtualKeyboardCommands.showVirtualKeyboard()

showVirtualKeyboard: () => boolean;

VirtualKeyboardCommands.switchKeyboardLayer()

switchKeyboardLayer: (mathfield, layer) => boolean;

VirtualKeyboardCommands.toggleVirtualKeyboard()

toggleVirtualKeyboard: () => boolean;

Selector

type Selector = Keys<Commands>;

Speech

SpeechScope

type SpeechScope = "all" | "selection" | "left" | "right" | "group" | "parent";

How much of the formula should be spoken:

all	the entire formula
selection	the selection portion of the formula
left	the element to the left of the selection
right	the element to the right of the selection
group	the group (numerator, root, etc..) the selection is in
parent	the parent of the selection

Keyboard Shortcuts

InlineShortcutDefinition

type InlineShortcutDefinition = 
  | string
  | {
  after: string;
  value: string;
};

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: {
         after: 'space+letter+digit+symbol+fence',
         value: '\\in',
     },
 };

When using a string, the shortcut applies regardless of the characters surrounding it.

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

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

Possible values are:

"space"	A spacing command, such as \quad
"nothing"	The begining of a group
"surd"	A square root or n-th root
"frac"	A fraction
"function"	A function such as \sin or f
"letter"	A letter, such as x or n
"digit"	0 through 9
"binop"	A binary operator, such as +
"relop"	A relational operator, such as =
"punct"	A punctuation mark, such as ,
"array"	An array, such as a matrix or cases statement
"openfence"	An opening fence, such as (
"closefence"	A closing fence such as }
"text"	Some plain text

InlineShortcutDefinitions

type InlineShortcutDefinitions = Record<string, InlineShortcutDefinition>;

Keybinding

type Keybinding = {
  command:   | Selector
     | string[]
     | [string, any]
     | [string, any, any]
     | [string, any, any, any];
  ifLayout: string[];
  ifMode: ParseMode;
  ifPlatform:   | "macos"
     | "!macos"
     | "windows"
     | "!windows"
     | "linux"
     | "!linux"
     | "ios"
     | "!ios"
     | "android"
     | "!android"
     | "chromeos"
     | "!chromeos";
  key: string;
};

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}'],
}

Keybinding.command

command: 
  | Selector
  | string[]
  | [string, any]
  | [string, any, any]
  | [string, any, any, any];

The command is a single selector, or a selector with arguments

Keybinding.ifMode?

optional ifMode: ParseMode;

If specified, this indicates in which mode this keybinding will apply. If none is specified, the keybinding will apply in every mode.

Keybinding.ifPlatform?

optional ifPlatform: 
  | "macos"
  | "!macos"
  | "windows"
  | "!windows"
  | "linux"
  | "!linux"
  | "ios"
  | "!ios"
  | "android"
  | "!android"
  | "chromeos"
  | "!chromeos";

If specified, this indicates the OS platform to which this keybinding apply.

For example, if set to !macos this key binding will apply to every platform, except macOS.

Keybinding.key

key: string;

The pressed keys that will trigger this keybinding.

The key is made up of modifiers and the key itself.

The following modifiers can be used:

Platform	Modifiers
macOS, iOS	ctrl, shift, alt, cmd
Windows	ctrl, shift, alt, win
Linux, Android, ChromeOS	ctrl, shift, alt, meta

If the cmd modifier is used, the keybinding will only apply on macOS. If the win modifier is used, the keybinding will only apply to Windows. If the meta modifier is used, the keybinding will apply to platforms other than macOS or Windows.

The alt key is the option key on Apple keyboards.

The following values for keys can be used:

• a–z, 0–9
• `, -, =, [, ], \, ;, ', ,, ., /
• left, up, right, down, pageup, pagedown, end, home
• tab, enter, escape, space, backspace, delete
• f1–f19
• pausebreak, capslock, insert
• numpad0–numpad9, numpad_multiply, numpad_add, numpad_separator
• numpad_subtract, numpad_decimal, numpad_divide

The values will be remapped based on the current keyboard layout. So, for example if a is used, on a French AZERTY keyboard the keybinding will be associated with the key labeled 'A' (event though it corresponds to the key labeled 'Q' on a US QWERTY keyboard).

To associate keybindings with physical keys independent of the keyboard layout, use the following keycodes:

• [KeyA]–[KeyZ], [Digit0]–[Digit9]
• [Backquote], [Minus], [Equal], [BracketLeft], [BracketRight], [Backslash], [Semicolon], [Quote], [Comma], [Period], [Slash]
• [ArrowLeft], [ArrowUp], [ArrowRight], [ArrowDown], [PageUp], [PageDown], [End], [Home]
• [Tab], [Enter], [Escape], [Space], [Backspace], [Delete]
• [F1]–[F19]
• [Pause], [CapsLock], [Insert]
• [Numpad0]–[Numpad9], [NumpadMultiply], [NumpadAdd], [NumpadComma]
• [NumpadSubtract], [NumpadDecimal], [NumpadDivide]

For example, using [KeyQ] will map to the the key labeled 'Q' on a QWERTY keyboard, and to the key labeled 'A' on an AZERTY keyboard.

As a general guideline, it is preferable to use the key values a–z for keybinding that are pseudo-mnemotechnic. For the other, it is generally preferable to use the keycodes.

Consider the key combination: alt+2. With an AZERTY (French) layout, the digits (i.e. '2') are only accessible when shifted. The '2' key produces 'é' when not shifted. It is therefore impossible on an AZERTY keyboard to produce the alt+2 key combination, at best it would be alt+shift+2. To indicate that the intended key combination should be alt and the key on the keyboard which has the position of the 2 key on a US keyboard, a key code should be used instead: alt+[Digit2]. This will correspond to a key combination that can be generated on any keyboard.

Virtual Keyboard

NormalizedVirtualKeyboardLayer

NormalizedVirtualKeyboardLayer.backdrop?

optional backdrop: string;

NormalizedVirtualKeyboardLayer.container?

optional container: string;

NormalizedVirtualKeyboardLayer.id?

optional id: string;

NormalizedVirtualKeyboardLayer.markup?

optional markup: string;

NormalizedVirtualKeyboardLayer.rows?

optional rows: Partial<VirtualKeyboardKeycap>[][];

NormalizedVirtualKeyboardLayer.style?

optional style: string;

VirtualKeyboardInterface

This interface is implemented by:

• VirtualKeyboard: when the browsing context is a top-level document
• VirtualKeyboardProxy: when the browsing context is an iframe

Extends

• VirtualKeyboardOptions

VirtualKeyboardInterface.boundingRect

readonly boundingRect: DOMRect;

VirtualKeyboardInterface.isShifted

readonly isShifted: boolean;

VirtualKeyboardInterface.normalizedLayouts

readonly normalizedLayouts: VirtualKeyboardLayoutCore & {
  layers: NormalizedVirtualKeyboardLayer[];
 }[];

This property is the "expanded" version of the layouts property. It is normalized to include all the default values for the properties of the layout and layers.

VirtualKeyboardInterface.originValidator

originValidator: OriginValidator;

Specify behavior how origin of message from postMessage should be validated.

Default: "none"

VirtualKeyboardInterface.targetOrigin

targetOrigin: string;

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

Default: globalThis.origin

VirtualKeyboardInterface.visible

visible: boolean;

VirtualKeyboardInterface.alphabeticLayout

set alphabeticLayout(value: AlphabeticKeyboardLayout): void

Layout of the alphabetic layers: AZERTY, QWERTY, etc...

VirtualKeyboardInterface.container

set container(value: HTMLElement): void

Element the virtual keyboard element gets appended to.

When using full screen elements that contain mathfield, set this property to the full screen element to ensure the virtual keyboard will be visible.

Default: document.body

VirtualKeyboardInterface.editToolbar

set editToolbar(value: EditToolbarOptions): void

Configuration of the action toolbar, displayed on the right-hand side.

Use "none" to disable the right hand side toolbar of the virtual keyboard.

VirtualKeyboardInterface.layouts

get layouts(): readonly (
  | VirtualKeyboardLayout
  | VirtualKeyboardName)[]
set layouts(value: 
  | VirtualKeyboardLayout
  | VirtualKeyboardName
  | VirtualKeyboardLayout | VirtualKeyboardName[]
  | readonly VirtualKeyboardLayout | VirtualKeyboardName[]): void

A layout is made up of one or more layers (think of the main layer and the shift layer on a hardware keyboard).

A layout has a name and styling information.

In addition, a layout can be represented as a standard name which includes "numeric", "functions", "symbols", "alphabetic" and `"greek".

*See mathfield/guides/virtual-keyboards | Guide: Virtual Keyboards

VirtualKeyboardInterface.connect()

connect(): void

VirtualKeyboardInterface.disconnect()

disconnect(): void

VirtualKeyboardInterface.executeCommand()

executeCommand(command): boolean

command

string | [string, ...any[]]

VirtualKeyboardInterface.getKeycap()

getKeycap(keycap): Partial<VirtualKeyboardKeycap>

Some keycaps can be customized: [left], [right], [up], [down], [return], [action], [space], [tab], [backspace], [shift], [undo], [redo], [foreground-color], [background-color], [hide-keyboard], [.], [,], [0], [1], [2], [3], [4], [5], [6], [7], [8], [9], [+], [-], [*], [/], [^], [_], [=], [.], [(], [)],

keycap

string

VirtualKeyboardInterface.hide()

hide(options?): void

options?

animate

boolean

VirtualKeyboardInterface.setKeycap()

setKeycap(keycap, value): void

keycap

string

value

Partial<VirtualKeyboardKeycap>

VirtualKeyboardInterface.show()

show(options?): void

options?

animate

boolean

VirtualKeyboardInterface.update()

update(mf): void

mf

MathfieldProxy

VirtualKeyboardInterface.updateToolbar()

updateToolbar(mf): void

The content or selection of the mathfield has changed and the toolbar may need to be updated accordingly

mf

MathfieldProxy

VirtualKeyboardKeycap

VirtualKeyboardKeycap.aside

aside: string;

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

VirtualKeyboardKeycap.class

class: string;

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.
• shift: a shift key
• 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

VirtualKeyboardKeycap.command

command: 
  | string
  | string[]
  | [string, any]
  | [string, any, any]
  | [string, any, any, any];

Command to perform when the keycap is pressed

VirtualKeyboardKeycap.insert

insert: string;

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

VirtualKeyboardKeycap.key

key: string;

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

VirtualKeyboardKeycap.label

label: string;

The HTML markup displayed for the keycap

VirtualKeyboardKeycap.latex

latex: string;

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

VirtualKeyboardKeycap.layer

layer: string;

Name of the layer to shift to when the key is pressed

VirtualKeyboardKeycap.shift

shift: 
  | string
| Partial<VirtualKeyboardKeycap>;

Variant of the keycap when the shift key is pressed

VirtualKeyboardKeycap.stickyVariantPanel

stickyVariantPanel: boolean;

Open variants panel without long press and does not close automatically

VirtualKeyboardKeycap.tooltip

tooltip: string;

VirtualKeyboardKeycap.variants

variants: 
  | string
  | (
  | string
  | Partial<VirtualKeyboardKeycap>)[];

A set of keycap variants displayed on a long press

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

VirtualKeyboardKeycap.width

width: 0.5 | 1 | 1.5 | 2 | 5;

Width of the keycap, as a multiple of the standard keycap width

VirtualKeyboardLayer

VirtualKeyboardLayer.backdrop?

optional backdrop: string;

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

VirtualKeyboardLayer.container?

optional container: string;

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

VirtualKeyboardLayer.id?

optional id: string;

A unique string identifying the layer

VirtualKeyboardLayer.markup?

optional markup: string;

VirtualKeyboardLayer.rows?

optional rows: (
  | string
  | Partial<VirtualKeyboardKeycap>)[][];

The rows of keycaps in this layer

VirtualKeyboardLayer.style?

optional style: string;

The CSS stylesheet associated with this layer

VirtualKeyboardOptions

Extended by

• VirtualKeyboardInterface

VirtualKeyboardOptions.normalizedLayouts

readonly normalizedLayouts: VirtualKeyboardLayoutCore & {
  layers: NormalizedVirtualKeyboardLayer[];
 }[];

This property is the "expanded" version of the layouts property. It is normalized to include all the default values for the properties of the layout and layers.

VirtualKeyboardOptions.originValidator

originValidator: OriginValidator;

Specify behavior how origin of message from postMessage should be validated.

Default: "none"

VirtualKeyboardOptions.targetOrigin

targetOrigin: string;

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

Default: globalThis.origin

VirtualKeyboardOptions.alphabeticLayout

set alphabeticLayout(value: AlphabeticKeyboardLayout): void

Layout of the alphabetic layers: AZERTY, QWERTY, etc...

VirtualKeyboardOptions.container

set container(value: HTMLElement): void

Element the virtual keyboard element gets appended to.

When using full screen elements that contain mathfield, set this property to the full screen element to ensure the virtual keyboard will be visible.

Default: document.body

VirtualKeyboardOptions.editToolbar

set editToolbar(value: EditToolbarOptions): void

Configuration of the action toolbar, displayed on the right-hand side.

Use "none" to disable the right hand side toolbar of the virtual keyboard.

VirtualKeyboardOptions.layouts

get layouts(): readonly (
  | VirtualKeyboardLayout
  | VirtualKeyboardName)[]
set layouts(value: 
  | VirtualKeyboardLayout
  | VirtualKeyboardName
  | VirtualKeyboardLayout | VirtualKeyboardName[]
  | readonly VirtualKeyboardLayout | VirtualKeyboardName[]): void

A layout is made up of one or more layers (think of the main layer and the shift layer on a hardware keyboard).

A layout has a name and styling information.

In addition, a layout can be represented as a standard name which includes "numeric", "functions", "symbols", "alphabetic" and `"greek".

*See mathfield/guides/virtual-keyboards | Guide: Virtual Keyboards

VirtualKeyboardOptions.getKeycap()

getKeycap(keycap): Partial<VirtualKeyboardKeycap>

Some keycaps can be customized: [left], [right], [up], [down], [return], [action], [space], [tab], [backspace], [shift], [undo], [redo], [foreground-color], [background-color], [hide-keyboard], [.], [,], [0], [1], [2], [3], [4], [5], [6], [7], [8], [9], [+], [-], [*], [/], [^], [_], [=], [.], [(], [)],

keycap

string

VirtualKeyboardOptions.setKeycap()

setKeycap(keycap, value): void

keycap

string

value

Partial<VirtualKeyboardKeycap>

AlphabeticKeyboardLayout

type AlphabeticKeyboardLayout = "auto" | "qwerty" | "azerty" | "qwertz" | "dvorak" | "colemak";

EditToolbarOptions

type EditToolbarOptions = "none" | "default";

NormalizedVirtualKeyboardLayout

type NormalizedVirtualKeyboardLayout = VirtualKeyboardLayoutCore & {
  layers: NormalizedVirtualKeyboardLayer[];
};

OriginValidator

type OriginValidator = (origin) => boolean | "same-origin" | "none";

Specify behavior for origin validation when using the virtual keyboard.

Value	Description
"same-origin"	The origin of received message must be the same of hosted window, instead exception will throw.
(origin: string) => boolean	The callback to verify origin to be expected validation. When callback return false value, message will rejected and exception will throw.
"none"	No origin validation for post messages.

VirtualKeyboardLayout

type VirtualKeyboardLayout = VirtualKeyboardLayoutCore & 
  | {
  layers: (string | VirtualKeyboardLayer)[];
 }
  | {
  rows: (
     | string
     | Partial<VirtualKeyboardKeycap>)[][];
 }
  | {
  markup: string;
};

VirtualKeyboardLayoutCore

type VirtualKeyboardLayoutCore = {
  displayEditToolbar: boolean;
  displayShiftedKeycaps: boolean;
  id: string;
  label: string;
  labelClass: string;
  tooltip: string;
};

VirtualKeyboardLayoutCore.displayEditToolbar?

optional displayEditToolbar: boolean;

If false, do not include the edit toolbar in the layout

VirtualKeyboardLayoutCore.displayShiftedKeycaps?

optional displayShiftedKeycaps: boolean;

If false, keycaps that have a shifted variant will be displayed as if they don't

VirtualKeyboardLayoutCore.id?

optional id: string;

A unique string identifying the layout

VirtualKeyboardLayoutCore.label?

optional label: string;

A human readable string displayed in the layout switcher toolbar

VirtualKeyboardLayoutCore.tooltip?

optional tooltip: string;

A human readable tooltip associated with the label

VirtualKeyboardMessage

type VirtualKeyboardMessage = 
  | {
  action: "execute-command";
  command:   | Selector
     | [Selector, ...any[]];
  type: "mathlive#virtual-keyboard-message";
 }
  | {
  action: "geometry-changed";
  boundingRect: DOMRect;
  type: "mathlive#virtual-keyboard-message";
 }
  | {
  action: "synchronize-proxy";
  alphabeticLayout: AlphabeticKeyboardLayout;
  boundingRect: DOMRect;
  editToolbar: EditToolbarOptions;
  isShifted: boolean;
  layers: Record<string, 
     | string
     | Partial<VirtualKeyboardLayer>>;
  layouts: Readonly<(string | VirtualKeyboardLayout)[]>;
  setKeycap: {
     keycap: string;
     value: Partial<VirtualKeyboardKeycap>;
    };
  type: "mathlive#virtual-keyboard-message";
 }
  | {
  action: "update-setting";
  alphabeticLayout: AlphabeticKeyboardLayout;
  editToolbar: EditToolbarOptions;
  layers: Record<string, 
     | string
     | Partial<VirtualKeyboardLayer>>;
  layouts: Readonly<(
     | VirtualKeyboardName
     | VirtualKeyboardLayout)[]>;
  setKeycap: {
     keycap: string;
     value: Partial<VirtualKeyboardKeycap>;
    };
  type: "mathlive#virtual-keyboard-message";
 }
  | {
  action: "show" | "hide";
  animate: boolean;
  type: "mathlive#virtual-keyboard-message";
 }
  | {
  action:   | "connect"
     | "disconnect"
     | "proxy-created"
     | "focus"
     | "blur"
     | "update-state"
     | "update-toolbar";
  type: "mathlive#virtual-keyboard-message";
};

VirtualKeyboardMessageAction

type VirtualKeyboardMessageAction = 
  | "connect"
  | "disconnect"
  | "proxy-created"
  | "execute-command"
  | "show"
  | "hide"
  | "update-setting"
  | "update-toolbar"
  | "synchronize-proxy"
  | "geometry-changed"
  | "update-state"
  | "focus"
  | "blur";

VirtualKeyboardName

type VirtualKeyboardName = 
  | "default"
  | "compact"
  | "minimalist"
  | "numeric-only"
  | "numeric"
  | "symbols"
  | "alphabetic"
  | "greek";

VirtualKeyboardPolicy

type VirtualKeyboardPolicy = "auto" | "manual" | "sandboxed";

• "auto": the virtual keyboard is triggered when a mathfield is focused on a touch capable device.
• "manual": the virtual keyboard is not triggered automatically
• "sandboxed": the virtual keyboard is displayed in the current browsing context (iframe) if it has a defined container or is the top-level browsing context.

Localization

KeyboardLayoutName

type KeyboardLayoutName = 
  | "apple.en-intl"
  | "apple.french"
  | "apple.german"
  | "apple.spanish"
  | "dvorak"
  | "windows.en-intl"
  | "windows.french"
  | "windows.german"
  | "windows.spanish"
  | "linux.en"
  | "linux.french"
  | "linux.german"
  | "linux.spanish";

See setKeyboardLayout.

Name	Platform	Display name
"apple.en-intl"	Apple	English (International)
"apple.french"	Apple	French (AZERTY)
"apple.german"	Apple	German (QWERTZ)
"dvorak"		English (Dvorak)
"windows.en-intl"	Windows	English (International)
"windows.french"	Windows	French (AZERTY)
"windows.german"	Windows	German (QWERTZ)
"linux.en"	Linux	English
"linux.french"	Linux	French (AZERTY)
"linux.german"	Linux	German (QWERTZ)

setKeyboardLayout()

function setKeyboardLayout(name): void

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.

name

"auto" | KeyboardLayoutName

setKeyboardLayoutLocale()

function setKeyboardLayoutLocale(locale): void

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.

locale

string

Static Rendering

StaticRenderOptions

type StaticRenderOptions = Partial<LayoutOptions> & {
  asciiMath: {
     delimiters: {
        display: string[];
        inline: string[];
       };
    };
  ignoreClass: string;
  processClass: string;
  processMathJSONScriptType: string;
  processScriptType: string;
  readAloud: boolean;
  renderAccessibleContent: string;
  skipTags: string[];
  TeX: {
     className: {
        display: string;
        inline: string;
       };
     delimiters: {
        display: [string, string][];
        inline: [string, string][];
       };
     processEnvironments: boolean;
    };
};

StaticRenderOptions.ignoreClass?

optional ignoreClass: string;

A string used as a regular expression of class names of elements whose content will not be scanned for delimiter

Default: "tex2jax_ignore"

StaticRenderOptions.processClass?

optional processClass: string;

A string used as a regular expression of class names of elements whose content will be scanned for delimiters, even if their tag name or parent class name would have prevented them from doing so.

Default: "tex2jax_process"

StaticRenderOptions.processMathJSONScriptType?

optional processMathJSONScriptType: string;

<script> tags with this type will be processed as MathJSON.

Default: "math/json"

StaticRenderOptions.processScriptType?

optional processScriptType: string;

<script> tags with this type will be processed as LaTeX.

Default: "math/tex"

StaticRenderOptions.readAloud?

optional readAloud: boolean;

If true, generate markup that can be read aloud later using speak

Default: false

StaticRenderOptions.renderAccessibleContent?

optional renderAccessibleContent: string;

The format(s) in which to render the math for screen readers:

• "mathml" MathML
• "speakable-text" Spoken representation

You can pass an empty string to turn off the rendering of accessible content. You can pass multiple values separated by spaces, e.g "mathml speakable-text"

Default: "mathml"

StaticRenderOptions.skipTags?

optional skipTags: string[];

An array of tag names whose content will not be scanned for delimiters (unless their class matches the processClass pattern below).

Default: ['math-field', 'noscript', 'style', 'textarea', 'pre', 'code', 'annotation', 'annotation-xml']

renderMathInDocument()

function renderMathInDocument(options?): void

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

Caution

This is a very expensive call, as it needs to parse the entire DOM tree to determine which elements need to be processed. In most cases this should only be called once per document, once the DOM has been loaded.

To render a specific element, use renderMathInElement()

options?

StaticRenderOptions

Example

import { renderMathInDocument } from 'https://unpkg.com/mathlive?module';
renderMathInDocument();

renderMathInElement()

function renderMathInElement(element, options?): void

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

element

An HTML DOM element, or a string containing the ID of an element.

string | HTMLElement

options?

StaticRenderOptions

Example

import { renderMathInElement } from 'https://unpkg.com/mathlive?module';
renderMathInElement("formula");

Conversion

LatexSyntaxError<T>

type LatexSyntaxError<T> = {
  after: string;
  arg: string;
  before: string;
  code: T;
  latex: string;
};

Type Parameters

• T = ParserErrorCode

ParserErrorCode

type ParserErrorCode = 
  | "unknown-command"
  | "invalid-command"
  | "unbalanced-braces"
  | "unknown-environment"
  | "unbalanced-environment"
  | "unbalanced-mode-shift"
  | "missing-argument"
  | "too-many-infix-commands"
  | "unexpected-command-in-string"
  | "missing-unit"
  | "unexpected-delimiter"
  | "unexpected-token"
  | "unexpected-end-of-string"
  | "improper-alphabetic-constant";

Error codes returned by the mf.errors property.

unknown-command	There is no definition available for this LaTeX command, e.g. \zin
unknown-environment	There is no definition available for this environment, e.g. \begin{foo}
invalid-command	This command is not valid in the current context (e.g. text command in math mode)
unbalanced-braces	There are too many or too few { or }
unbalanced-environment	An environment was open but never closed (\begin{array}) or the \end command does not match the \begin command (\begin{array*}\end{array})
unbalanced-mode-shift	A $, $$, \( or \[ was not balanced
missing-argument	A required argument is missing, e.g. \frac{2}
too-many-infix-commands	A group can include only one infix command (i.e. \choose, \atop). In general it's best to avoid infix commands.
unexpected-command-in-string	A command expected a string argument, but there was a command instead
missing-unit	An argument requiring a dimension was missing an unit.
unexpected-delimiter	An invalid symbol or command was used as a delimiter.
unexpected-token	An unexpected character was encountered.
unexpected-end-of-string	The end of the string was reached, but some required arguments were missing.
improper-alphabetic-constant	The alphabetic constant prefix ` was not followed by a letter or single character command.

convertAsciiMathToLatex()

function convertAsciiMathToLatex(ascii): string

Convert an AsciiMath string to a LaTeX string.

convertAsciiMathToLatex("1/2");
// -> "\\frac{1}{2}"

ascii

string

convertLatexToAsciiMath()

function convertLatexToAsciiMath(latex, parseMode): string

Convert a LaTeX string to a string of AsciiMath.

convertLatexToAsciiMath("\\frac{1}{2}");
// -> "1/2"

latex

string

parseMode

ParseMode = 'math'

convertLatexToMarkup()

function convertLatexToMarkup(text, options?): string

Convert a LaTeX string to a string of HTML markup.

Note

This function does not interact with the DOM. It does not load fonts or inject stylesheets in the document. It can safely be used on the server side.

To get the output of this function to correctly display in a document, use the mathlive static style sheet by adding the following to the <head> of the document:

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

text

string

A string of valid LaTeX. It does not have to start with a mode token such as $$ or \(.

options?

Partial<LayoutOptions>

convertLatexToMathMl()

function convertLatexToMathMl(latex, options): string

Convert a LaTeX string to a string of MathML markup.

latex

string

A string of valid LaTeX. It does not have to start with a mode token such as a $$ or \(.

options

generateID?

boolean

If true, add an "extid" attribute to the MathML nodes with a value matching the atomID. This can be used to map items on the screen with their MathML representation or vice-versa.

convertLatexToSpeakableText()

function convertLatexToSpeakableText(latex): string

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

latex

string

A string of valid LaTeX. It does not have to start with a mode token such as a $$ or \(.

Example

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

convertMathJsonToLatex()

function convertMathJsonToLatex(json): string

Convert a MathJSON expression to a LaTeX string.

convertMathJsonToLatex(["Add", 1, 2]);
// -> "1 + 2"

json

Expression

validateLatex()

function validateLatex(s): LatexSyntaxError[]

Check if a string of LaTeX is valid and return an array of syntax errors.

s

string

MathJSON

Expression

type Expression = 
  | number
  | string
  | {}
  | [Expression, ...Expression[]];

Other

version

const version: {
  mathlive: string;
};

Current version: {{SDK_VERSION}}

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