MathLive

module mathliveClasses

interface Commands

Use with Mathfield.executeCommand or MathfieldElement.executeCommand.

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

Commands return true if they resulted in a dirty state.

Array

Auto-complete

Clipboard

Deleting

Prompt

Scrolling

Selection

Undo/Redo

Other

Array

interface Commandscommand​addColumnAfter

executeCommand("addColumnAfter"): boolean

interface Commandscommand​addColumnBefore

executeCommand("addColumnBefore"): boolean

interface Commandscommand​addRowAfter

executeCommand("addRowAfter"): boolean

interface Commandscommand​addRowBefore

executeCommand("addRowBefore"): boolean

interface Commandscommand​removeColumn

executeCommand("removeColumn"): boolean

interface Commandscommand​removeRow

executeCommand("removeRow"): boolean

interface Commandscommand​setEnvironment

executeCommand(["setEnvironment", environment: TabularEnvironment]): boolean
environment: TabularEnvironment

Auto-complete

interface Commandscommand​complete

executeCommand("complete"): boolean

interface Commandscommand​nextSuggestion

executeCommand("nextSuggestion"): boolean

interface Commandscommand​previousSuggestion

executeCommand("previousSuggestion"): boolean

Clipboard

interface Commandscommand​copyToClipboard

executeCommand("copyToClipboard"): boolean

interface Commandscommand​cutToClipboard

executeCommand("cutToClipboard"): boolean

interface Commandscommand​pasteFromClipboard

executeCommand("pasteFromClipboard"): boolean

Deleting

interface Commandscommand​deleteAll

executeCommand("deleteAll"): boolean

interface Commandscommand​deleteBackward

executeCommand("deleteBackward"): boolean

interface Commandscommand​deleteForward

executeCommand("deleteForward"): boolean

interface Commandscommand​deleteNextWord

executeCommand("deleteNextWord"): boolean

interface Commandscommand​deletePreviousWord

executeCommand("deletePreviousWord"): boolean

interface Commandscommand​deleteToGroupEnd

executeCommand("deleteToGroupEnd"): boolean

interface Commandscommand​deleteToGroupStart

executeCommand("deleteToGroupStart"): boolean

interface Commandscommand​deleteToMathFieldEnd

executeCommand("deleteToMathFieldEnd"): boolean

interface Commandscommand​deleteToMathFieldStart

executeCommand("deleteToMathFieldStart"): boolean

Prompt

interface Commandscommand​insertPrompt

executeCommand(["insertPrompt", id?: string, options?: InsertOptions]): boolean
id: string
options: InsertOptions

Scrolling

interface Commandscommand​scrollIntoView

executeCommand("scrollIntoView"): boolean

interface Commandscommand​scrollToEnd

executeCommand("scrollToEnd"): boolean

interface Commandscommand​scrollToStart

executeCommand("scrollToStart"): boolean

Selection

interface Commandscommand​extendSelectionBackward

executeCommand("extendSelectionBackward"): boolean

interface Commandscommand​extendSelectionDownward

executeCommand("extendSelectionDownward"): boolean

interface Commandscommand​extendSelectionForward

executeCommand("extendSelectionForward"): boolean

interface Commandscommand​extendSelectionUpward

executeCommand("extendSelectionUpward"): boolean

interface Commandscommand​extendToGroupEnd

executeCommand("extendToGroupEnd"): boolean

interface Commandscommand​extendToGroupStart

executeCommand("extendToGroupStart"): boolean

interface Commandscommand​extendToMathFieldEnd

executeCommand("extendToMathFieldEnd"): boolean

interface Commandscommand​extendToMathFieldStart

executeCommand("extendToMathFieldStart"): boolean

interface Commandscommand​extendToNextBoundary

executeCommand("extendToNextBoundary"): boolean

interface Commandscommand​extendToNextWord

executeCommand("extendToNextWord"): boolean

interface Commandscommand​extendToPreviousBoundary

executeCommand("extendToPreviousBoundary"): boolean

interface Commandscommand​extendToPreviousWord

executeCommand("extendToPreviousWord"): boolean

interface Commandscommand​moveAfterParent

executeCommand("moveAfterParent"): boolean

interface Commandscommand​moveBeforeParent

executeCommand("moveBeforeParent"): boolean

interface Commandscommand​moveDown

executeCommand("moveDown"): boolean

interface Commandscommand​moveToGroupEnd

executeCommand("moveToGroupEnd"): boolean

interface Commandscommand​moveToGroupStart

executeCommand("moveToGroupStart"): boolean

interface Commandscommand​moveToMathfieldEnd

executeCommand("moveToMathfieldEnd"): boolean

interface Commandscommand​moveToMathfieldStart

executeCommand("moveToMathfieldStart"): boolean

interface Commandscommand​moveToNextChar

executeCommand("moveToNextChar"): boolean

interface Commandscommand​moveToNextPlaceholder

executeCommand("moveToNextPlaceholder"): boolean

interface Commandscommand​moveToNextWord

executeCommand("moveToNextWord"): boolean

interface Commandscommand​moveToOpposite

executeCommand("moveToOpposite"): boolean

interface Commandscommand​moveToPreviousChar

executeCommand("moveToPreviousChar"): boolean

interface Commandscommand​moveToPreviousPlaceholder

executeCommand("moveToPreviousPlaceholder"): boolean

interface Commandscommand​moveToPreviousWord

executeCommand("moveToPreviousWord"): boolean

interface Commandscommand​moveToSubscript

executeCommand("moveToSubscript"): boolean

interface Commandscommand​moveToSuperscript

executeCommand("moveToSuperscript"): boolean

interface Commandscommand​moveUp

executeCommand("moveUp"): boolean

interface Commandscommand​selectAll

executeCommand("selectAll"): boolean

interface Commandscommand​selectGroup

executeCommand("selectGroup"): boolean

Undo/Redo

interface Commandscommand​redo

executeCommand("redo"): boolean

interface Commandscommand​undo

executeCommand("undo"): boolean

Other

interface Commandscommand​applyStyle

executeCommand(["applyStyle", style: Style]): boolean
style: Style

interface Commandscommand​commit

executeCommand("commit"): boolean

interface Commandscommand​insert

executeCommand(["insert", s: string, options: InsertOptions]): boolean
s: string
options: InsertOptions

interface Commandscommand​insertDecimalSeparator

executeCommand("insertDecimalSeparator"): boolean

interface Commandscommand​performWithFeedback

executeCommand(["performWithFeedback", command: string]): boolean
command: string

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

interface Commandscommand​plonk

executeCommand("plonk"): boolean

interface Commandscommand​speak

executeCommand(["speak", scope: SpeechScope, options: {withHighlighting: boolean}]): boolean
scope: SpeechScope
options:
withHighlighting: boolean;

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

interface Commandscommand​switchMode

executeCommand(["switchMode", mode: ParseMode]): boolean
mode: ParseMode

interface Commandscommand​toggleKeystrokeCaption

executeCommand("toggleKeystrokeCaption"): boolean

interface Commandscommand​typedText

executeCommand(["typedText", options: {feedback: boolean; focus: boolean; simulateKeystroke: boolean}]): boolean
options:
feedback: boolean;

If true, provide audio and haptic feedback

focus: boolean;

If true, the mathfield will be focused

simulateKeystroke: boolean;

If true, generate some synthetic keystrokes (useful to trigger inline shortcuts, for example).

interface Mathfield

applyStyle(style: Style, options?: ApplyStyleOptions): 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".

blur?(): void
executeCommand(command: Selector | [Selector, ...any[]]): boolean

Execute a Commands defined by a selector.

mfe.executeCommand('add-column-after');
mfe.executeCommand(['switch-mode', 'math']);
focus?(): void
getCaretPoint?(): null | {x: number; y: number}

The bottom location of the caret (insertion point) in viewport coordinates.

See also setCaretPoint

getPromptValue(placeholderId: string): string

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

getPrompts(filter?: {correctness: "undefined" | "correct" | "incorrect"; id: string; locked: boolean}): string[]
getValue(format?: OutputFormat): string

Return a textual representation of the content of the mathfield.

getValue(start: number, end: number, format?: OutputFormat): string

Return the value of the mathfield from start to end

getValue(range: Range | Selection, format?: OutputFormat): string

Return the value of the mathfield in range

getValue(arg1?: number | Range | OutputFormat | Selection, arg2?: number | OutputFormat, arg3?: OutputFormat): string
hasFocus(): boolean

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

insert(s: string, options?: InsertOptions): 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.

select(): void
setCaretPoint(x: number, y: number): boolean
setValue(latex?: string, options?: InsertOptions): void

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

class MathfieldElement

Extends HTMLElement

Implements Mathfield

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

It inherits many useful properties and methods from HTMLElement such as style, tabIndex, addEventListener(), getAttribute(), etc…

To create a new MathfieldElement:

// 1. Create a new MathfieldElement
const mfe = new MathfieldElement();
// 2. Attach it to the DOM
document.body.appendChild(mfe);

The MathfieldElement constructor has an optional argument of MathfieldOptions to configure the element. The options can also be modified later:

// Setting options during construction
const mfe = new MathfieldElement({ smartFence: false });
// Modifying options after construction
mfe.setOptions({ smartFence: true });

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");
CSS Variable Usage
--hue Hue of the highlight color and the caret
--contains-highlight-background-color Backround property for items that contain the caret
--primary-color Primary accent color, used for example in the virtual keyboard
--text-font-family The font stack used in text mode
--smart-fence-opacity Opacity of a smart fence (default is 50%)
--smart-fence-color Color of a smart fence (default is current color)

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

CSS Parts

To style the virtual keyboard toggle, use the virtual-keyboard-toggle CSS part. To use it, define a CSS rule with a ::part() selector for example:

math-field::part(virtual-keyboard-toggle) {
 color: red;
}

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:

 getElementById('mf').value = "\\sin x";
 getElementById('mf').letterShapeStyle = "text";

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

getElementById('mf').setAttribute('letter-shape-style',  'french');
console.log(getElementById('mf').letterShapeStyle);
// Result: "french"
getElementById('mf').letterShapeStyle ='tex;
console.log(getElementById('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
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 MathfieldOptions for more details about these options.

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

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

Events

Listen to these events by using 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.
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
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.
virtual-keyboard-toggle The visibility of the virtual keyboard panel has changed. Listen for this event on window.mathVirtualKeyboard
blur The mathfield is losing focus
focus The mathfield is gaining focus
focus-out The user is navigating out of the mathfield, typically using the tab key
`detail: {direction: ‘forward’
move-out The user has pressed an arrow key, but there is nowhere to go. This is an opportunity to change the focus to another element if desired.
`detail: {direction: ‘forward’
keystroke The user typed a keystroke with a physical keyboard
detail: {keystroke: string, event: KeyboardEvent}
mount The element has been attached to the DOM
unmount The element is about to be removed from the DOM

class MathfieldElementnew MathfieldElement()

new MathfieldElement(options?: Partial<MathfieldOptions>): 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);

class MathfieldElementProperties / Methods

Accessing and changing the content

Selection

Other

Focus

class MathfieldElement_fontsDirectory: null | string

static

class MathfieldElement_keypressSound

default: null | string;
delete: null | string;
return: null | string;
spacebar: null | string;
static

class MathfieldElement_plonkSound: null | string

static

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

class MathfieldElement_soundsDirectory: null | string

static

class MathfieldElementcreateHTML

(html: string): any
static

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.

class MathfieldElementfractionNavigationOrder: "numerator-denominator" | "denominator-numerator"

static

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"

class MathfieldElementkeypressVibration: boolean

static

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

class MathfieldElementreadAloudHook

(element: HTMLElement, text: string): void
static

class MathfieldElementspeakHook

(text: string): void
static

class MathfieldElementversion: string

static

Accessing and changing the content

class MathfieldElementapplyStyle()

applyStyle(style: Style, options?: ApplyStyleOptions): 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".

class MathfieldElementgetValue()

getValue(format?)
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"

→ string

Return a textual representation of the content of the mathfield.

getValue(start: number, end: number, format?: OutputFormat): string

Return the value of the mathfield from start to end

getValue(range: Range, format?: OutputFormat): string

Return the value of the mathfield in range

getValue(selection: Selection, format?: OutputFormat): string

class MathfieldElementinsert()

insert(s: string, options?: InsertOptions): 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.

class MathfieldElementsetValue()

setValue(latex?: string, options?: InsertOptions): void

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

class MathfieldElementvalue: string

The content of the mathfield as a LaTeX expression.

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

Selection

class MathfieldElementcaretPoint: null | {x: number; y: number}

The bottom location of the caret (insertion point) in viewport coordinates.

The bottom location of the caret (insertion point) in viewport coordinates.

class MathfieldElementhitboxFromOffset()

hitboxFromOffset(offset: number): null | DOMRect

The bounding rect of the atom at offset

class MathfieldElementlastOffset: number  read only

The last valid offset.

class MathfieldElementoffsetFromPoint()

offsetFromPoint(x, y, options?)
x: number
y: number
options?:
bias: 0 | 1 | -1;
→ 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.

class MathfieldElementposition: number

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

class MathfieldElementselect()

select(): void

Select the content of the mathfield.

class MathfieldElementselection

get selection(): Selection
set selection(number | Selection)

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.

class MathfieldElementsetCaretPoint()

setCaretPoint(x: number, y: number): boolean

x and y are in viewport coordinates.

Return true if the location of the point is a valid caret location.

See also caretPoint

Other

class MathfieldElementaudioContext: AudioContext  read only

class MathfieldElementbackgroundColorMap: (name: string): undefined | string

class MathfieldElementcanRedo()

canRedo(): boolean

Return whether there are redoable items (for parent components with their own undo/redo)

class MathfieldElementcanUndo()

canUndo(): boolean

Return whether there are undoable items (for parent components with their own undo/redo)

class MathfieldElementcolorMap: (name: string): undefined | string

class MathfieldElementcomputeEngine: null | ComputeEngine

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

class MathfieldElementdecimalSeparator: "," | "."

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: "."

class MathfieldElementdefaultMode: "math" | "text" | "inline-math"

class MathfieldElementdisabled: boolean

class MathfieldElementerrors: LatexSyntaxError<ParserErrorCode>[]  read only

class MathfieldElementexecuteCommand()

executeCommand(command)
command:

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');
→ boolean

Execute a Commands defined by a selector.

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

class MathfieldElementexpression: any

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';

class MathfieldElementfontsDirectory: null | string

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

class MathfieldElementform: null | HTMLFormElement  read only

class MathfieldElementformAssociated: boolean  read only

class MathfieldElementgetOffsetDepth()

getOffsetDepth(offset: number): number

The depth of an offset represent the depth in the expression tree.

class MathfieldElementgetPromptState()

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

class MathfieldElementgetPromptValue()

getPromptValue(placeholderId: string): string

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

class MathfieldElementgetPrompts()

getPrompts(filter?)
filter?:
correctness: "undefined" | "correct" | "incorrect";
id: string;
locked: boolean;
→ string[]

Return the id of the prompts matching the filter

class MathfieldElementhandleEvent()

handleEvent(evt: Event): void

class MathfieldElementinlineShortcutTimeout: number

class MathfieldElementinlineShortcuts: InlineShortcutDefinitions

class MathfieldElementisSelectionEditable: boolean  read only

class MathfieldElementkeybindings: Keybinding[]

class MathfieldElementkeypressSound

get keypressSound(): {default: null | string; delete: null | string; return: null | string; spacebar: null | string}
set keypressSound(null | string | {default: null | string; delete: null | string; return: null | string; spacebar: null | string})

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.

class MathfieldElementletterShapeStyle: "auto" | "tex" | "iso" | "french" | "upright"

class MathfieldElementloadSound()

loadSound(sound: "plonk" | "keypress" | "spacebar" | "delete" | "return"): Promise<void>

class MathfieldElementlocale: string

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

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

class MathfieldElementmacros: MacroDictionary

class MathfieldElementmathModeSpace: string

class MathfieldElementmathVirtualKeyboardPolicy: VirtualKeyboardPolicy

class MathfieldElementminFontScale: number

class MathfieldElementmode: ParseMode

class MathfieldElementname: string  read only

class MathfieldElementonExport: (from: Mathfield, latex: string, range: Range): string

class MathfieldElementonInlineShortcut: (sender: Mathfield, symbol: string): string

class MathfieldElementonPointerDown()

onPointerDown(): void

class MathfieldElementonScrollIntoView: null | (sender: Mathfield): void

class MathfieldElementplaceholderSymbol: string

class MathfieldElementplaySound()

playSound(name: "plonk" | "keypress" | "spacebar" | "delete" | "return"): Promise<void>

class MathfieldElementplonkSound: null | string

class MathfieldElementpopoverPolicy: "auto" | "off"

class MathfieldElementreadOnly: boolean

class MathfieldElementreadonly: boolean

class MathfieldElementregisters: Registers

class MathfieldElementremoveExtraneousParentheses: boolean

class MathfieldElementresetUndo()

resetUndo(): void

Reset the undo stack (for parent components with their own undo/redo)

class MathfieldElementscriptDepth: number | [number, number]

class MathfieldElementselectionIsCollapsed: boolean  read only

class MathfieldElementsetPromptContent()

setPromptContent(id: string, content: string, insertOptions: Omit<InsertOptions, "insertionMode">): void

class MathfieldElementsetPromptState()

setPromptState(id, state, locked?)
id: string
state:
  • | undefined
  • | "undefined"
  • | "correct"
  • | "incorrect"
locked?: boolean

class MathfieldElementsmartFence: boolean

class MathfieldElementsmartMode: boolean

class MathfieldElementsmartSuperscript: boolean

class MathfieldElementsoundsDirectory: null | string

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.

class MathfieldElementspeechEngine: "local" | "amazon"

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 Guide: Speech

class MathfieldElementspeechEngineRate: string

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.

class MathfieldElementspeechEngineVoice: string

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

class MathfieldElementstrings: Record<string, Record<string, string>>

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

Example

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

This will override the default localized strings.

class MathfieldElementstripPromptContent()

stripPromptContent(filter?)
filter?:
correctness: "undefined" | "correct" | "incorrect";
id: string;
locked: boolean;
→ Record<string, string>

Remove the contents of all prompts, and return an object with the prompt contents

class MathfieldElementtextToSpeechMarkup: "" | "ssml" | "ssml_step" | "mac"

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. &#91;&#91;ltr&#93;&#93;.

class MathfieldElementtextToSpeechRules: "mathlive" | "sre"

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 Guide: Speech

class MathfieldElementtextToSpeechRulesOptions: Record<string, string>

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

class MathfieldElementtype: string  read only

class MathfieldElementvirtualKeyboardTargetOrigin: string

Focus

class MathfieldElementblur()

blur(): void

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

class MathfieldElementfocus()

focus(): void

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

class MathfieldElementhasFocus()

hasFocus(): boolean

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

interface MathfieldElementAttributes

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

default-mode: string
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.

letter-shape-style: string
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.

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.
min-font-scale: number
popover-policy: string
read-only: boolean

When true, the user cannot edit the mathfield.

remove-extraneous-parentheses: boolean
script-depth: string
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.

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^{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: 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.

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

interface MathfieldHooks

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.

interface MathfieldHooksProperties / Methods

interface MathfieldHooksonExport()

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

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

interface MathfieldHooksonInlineShortcut()

onInlineShortcut(sender: Mathfield, symbol: string): string

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}}.

interface MathfieldHooksonScrollIntoView

A hook invoked when a 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.

interface MathfieldProxy

canRedo: boolean
canUndo: boolean
mode: ParseMode
selectionIsCollapsed: boolean
style: Style
value: string

interface Model

mathfield: Mathfield

interface NormalizedVirtualKeyboardLayer

backdrop?: string
container?: string
id?: string
markup?: string
rows?: Partial<VirtualKeyboardKeycap>[][]
style?: string

interface Style

Use a Style object literal to modify the visual appearance of a mathfield or a portion of a mathfield.

You can control the color (“ink”) and background color (“paper”), the font variant, weight (FontSeries), size and more.

See Also

backgroundColor?: string
color?: string
fontFamily?: FontFamily
fontSeries?: FontSeries
fontShape?: FontShape
fontSize?: FontSize | "auto"
variant?: Variant
variantStyle?: VariantStyle

interface VirtualKeyboardCommands

hideVirtualKeyboard(): boolean
performVariant(command: Selector | [Selector, ...any[]]): boolean

The command invoked when a variant key is pressed: hide the variants panel, then perform the command.

showVirtualKeyboard(): boolean
switchKeyboardLayer(layer: string): boolean
toggleVirtualKeyboard(): boolean

interface VirtualKeyboardInterface

This interface is implemented by:

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

interface VirtualKeyboardInterfaceProperties / Methods

interface VirtualKeyboardInterfaceboundingRect: DOMRect

interface VirtualKeyboardInterfaceconnect()

connect(): void

interface VirtualKeyboardInterfacedisconnect()

disconnect(): void

interface VirtualKeyboardInterfaceexecuteCommand()

executeCommand(command: string | [string, ...any[]]): boolean

interface VirtualKeyboardInterfacehide()

hide(options?: {animate: boolean}): void

interface VirtualKeyboardInterfaceshow()

show(options?: {animate: boolean}): void

interface VirtualKeyboardInterfaceupdate()

update(mf: MathfieldProxy): void

interface VirtualKeyboardInterfaceupdateToolbar()

updateToolbar(mf: MathfieldProxy): void

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

interface VirtualKeyboardInterfacevisible: boolean

interface VirtualKeyboardKeycap

aside: string

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

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
command: Selector | string[] | [string, any] | [string, any, any] | [string, any, any, any]

Command to perform when the keycap is pressed

insert: string

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

key: string

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

label: string

The HTML markup displayed for the keycap

latex: string

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

layer: string

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

shift: string | Partial<VirtualKeyboardKeycap>

Variant of the keycap when the shift key is pressed

tooltip: string
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' }
]
width: 1 | 2 | 5 | 0.5 | 1.5

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

interface VirtualKeyboardLayer

backdrop?: string

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

container?: string

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

id?: string

A unique string identifying the layer

markup?: string
rows?: (string | Partial<VirtualKeyboardKeycap>)[][]

The rows of keycaps in this layer

style?: string

The CSS stylesheet associated with this layer

interface VirtualKeyboardOptions

interface VirtualKeyboardOptionsProperties / Methods

interface VirtualKeyboardOptionsactionKeycap

set actionKeycap(string | Partial<VirtualKeyboardKeycap>)

interface VirtualKeyboardOptionsalphabeticLayout

set alphabeticLayout(AlphabeticKeyboardLayout)

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

interface VirtualKeyboardOptionsbackspaceKeycap

set backspaceKeycap(string | Partial<VirtualKeyboardKeycap>)

interface VirtualKeyboardOptionscontainer

set container(null | HTMLElement)

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

interface VirtualKeyboardOptionseditToolbar

set editToolbar(EditToolbarOptions)

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

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

interface VirtualKeyboardOptionslayouts

set layouts("default" | VirtualKeyboardLayout | (string | VirtualKeyboardLayout)[])

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 Guide: Virtual Keyboards

interface VirtualKeyboardOptionsoriginValidator: OriginValidator

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

Default: "none"

interface VirtualKeyboardOptionsshiftKeycap

set shiftKeycap(string | Partial<VirtualKeyboardKeycap>)

interface VirtualKeyboardOptionstabKeycap

set tabKeycap(string | Partial<VirtualKeyboardKeycap>)

interface VirtualKeyboardOptionstargetOrigin: 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

version

version: {mathlive: string}

Current 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

module mathliveTypes

AlignEnvironment

  • | "align"
  • | "align*"
  • | "aligned"
  • | "gather"
  • | "gathered"
  • | "split"
  • | "multline"

AlphabeticKeyboardLayout

  • | "auto"
  • | "qwerty"
  • | "azerty"
  • | "qwertz"
  • | "dvorak"
  • | "colemak"

ApplyStyleOptions

operation: "set" | "toggle";
range: Range;
silenceNotifications: boolean;

ArgumentType

  • | ParseMode
  • | "bbox" | "colspec" | "delim" | "value" | "rest" | "string" | "balanced-string" | "expression" | "auto"

AutoRenderOptions

TeX: {delimiters: {display: [openDelim: string, closeDelim: string][]; inline: [openDelim: string, closeDelim: string][]}; processEnvironments: boolean};
asciiMath: {delimiters: {display: [openDelim: string, closeDelim: string][]; inline: [openDelim: string, closeDelim: string][]}};
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"

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"

processMathJSONScriptType: string;

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

Default: "math/json"

processScriptType: string;

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

Default: "math/tex"

readAloud: boolean;

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

Default: false

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"

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

BoxCSSProperties

  • | "background-color"
  • | "border"
  • | "border-bottom"
  • | "border-color"
  • | "border-left"
  • | "border-radius"
  • | "border-right"
  • | "border-right-width"
  • | "border-top"
  • | "border-top-width"
  • | "box-sizing"
  • | "color"
  • | "display"
  • | "font-family"
  • | "left"
  • | "height"
  • | "line-height"
  • | "margin-top"
  • | "margin-left"
  • | "margin-right"
  • | "opacity"
  • | "padding"
  • | "padding-left"
  • | "padding-right"
  • | "position"
  • | "top"
  • | "bottom"
  • | "vertical-align"
  • | "width"
  • | "z-index"

CasesEnvironment

  • | "cases"
  • | "dcases"
  • | "rcases"

ContentChangeOptions

data: string | null;
dataTransfer: DataTransfer | null;
inputType: ContentChangeType;

ContentChangeType

  • | "insertText"
  • | "insertLineBreak"
  • | "insertFromPaste"
  • | "historyUndo"
  • | "historyRedo"
  • | "deleteByCut"
  • | "deleteContent"
  • | "deleteContentBackward"
  • | "deleteContentForward"
  • | "deleteWordBackward"
  • | "deleteWordForward"
  • | "deleteSoftLineBackward"
  • | "deleteSoftLineForward"
  • | "deleteHardLineBackward"
  • | "deleteHardLineForward"

Dimension

A dimension is used to specify the size of things

dimension: number;
unit: DimensionUnit;

DimensionUnit

  • | "pt"
  • | "mm"
  • | "cm"
  • | "ex"
  • | "px"
  • | "em"
  • | "bp"
  • | "dd"
  • | "pc"
  • | "in"
  • | "mu"
  • | "fil"
  • | "fill"
  • | "filll"

EditToolbarOptions

  • | "none"
  • | "default"

EditingOptions

mathModeSpace: string;

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)

mathVirtualKeyboardPolicy: "auto" | "manual" | "sandboxed";
placeholderSymbol: string;

The symbol used to represent a placeholder in an expression.

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

popoverPolicy: "auto" | "off";

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

Default: true

readOnly: boolean;

When true, the user cannot edit the mathfield. The mathfield can still be modified programatically.

Default: false

removeExtraneousParentheses: boolean;

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

Default: true

scriptDepth: number | [number, number];

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.

smartFence: boolean;

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.

smartMode: boolean;

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
smartSuperscript: boolean;

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.

Environment

ErrorListener

<T> = (err: LatexSyntaxError<T>): void

Expression

FocusOutEvent

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);
});
direction: "forward" | "backward";

FontFamily

  • | "none"
  • | "roman"
  • | "monospace"
  • | "sans-serif"

FontSeries

  • | "auto"
  • | "m"
  • | "b"
  • | "l"
  • | ""

FontShape

  • | "auto"
  • | "n"
  • | "it"
  • | "sl"
  • | "sc"
  • | ""

FontSize

  • | 1
  • | 2
  • | 3
  • | 4
  • | 5
  • | 6
  • | 7
  • | 8
  • | 9
  • | 10

Glue

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

glue: Dimension;
grow: Dimension;
shrink: Dimension;

InlineShortcutDefinition

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
  • | string
  • | {after: string; value: string}

InlineShortcutDefinitions

Record<string, InlineShortcutDefinition>

InlineShortcutsOptions

inlineShortcutTimeout: number;

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.

inlineShortcuts: InlineShortcutDefinitions;

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

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

InsertOptions

feedback: boolean;

If true, provide audio and haptic feedback

focus: boolean;

If true, the mathfield will be focused after the insertion

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
insertionMode: "replaceSelection" | "replaceAll" | "insertBefore" | "insertAfter";
mode: ParseMode | "auto";

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

resetStyle: boolean;

If true, the style after the insertion is the same as the style before. If false, the style after the insertion is the style of the last inserted atom.

scrollIntoView: boolean;

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

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
silenceNotifications: boolean;
style: Style;

Keybinding

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}'],
}
command: Selector | string[] | [string, any] | [string, any, any] | [string, any, any, any];

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

ifLayout: string[];
ifMode: ParseMode;

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

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.

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.

KeyboardLayoutName

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)
  • | "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"

KeyboardOptions

keybindings: Keybinding[];

LatexSyntaxError

<T> =
after: string;
arg: string;
before: string;
code: T;
latex: string;

LatexValue

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

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

LayoutOptions

defaultMode: "inline-math" | "math" | "text";

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
letterShapeStyle: "auto" | "tex" | "iso" | "french" | "upright";

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.

macros: MacroDictionary;

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.setConfig({
macros: {
...mf.getOption('macros'),
smallfrac: '^{#1}\\!\\!/\\!_{#2}',
},
});

Note that getOption() is called 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}
minFontScale: number;

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

registers: Registers;

LaTeX global registers override.

backgroundColorMap: (name: string): undefined | string;
colorMap: (name: string): undefined | string;

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

MacroDefinition

See Also

args: number;
captureSelection: boolean;
def: string;

Definition of the macro as a LaTeX expression

expand: boolean;

MacroDictionary

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

Record<string, string | Partial<MacroDefinition> | MacroPackageDefinition>

MacroPackageDefinition

captureSelection: boolean;
package: Record<string, string | MacroDefinition>;
primitive: boolean;

MathLiveGlobal

readAloudAudio: HTMLAudioElement;
readAloudCurrentMark: string;
readAloudCurrentToken: string;
readAloudElement: null | HTMLElement;
readAloudFinalToken: null | string;
readAloudMarks: {time: number; value: string}[];
readAloudMathField: any;
readAloudStatus: string;
readAloudTokens: string[];
version: string;

MathfieldOptions

MathstyleName

  • | "displaystyle"
  • | "textstyle"
  • | "scriptstyle"
  • | "scriptscriptstyle"

MatrixEnvironment

  • | "matrix"
  • | "matrix*"
  • | "pmatrix"
  • | "pmatrix*"
  • | "bmatrix"
  • | "bmatrix*"
  • | "Bmatrix"
  • | "Bmatrix*"
  • | "vmatrix"
  • | "vmatrix*"
  • | "Vmatrix"
  • | "Vmatrix*"

MoveOutEvent

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.

direction: "forward" | "backward" | "upward" | "downward";

NormalizedMacroDictionary

Record<string, MacroDefinition>

NormalizedVirtualKeyboardLayout

Offset

A position of the caret/insertion point from the beginning of the formula.

number

OriginValidator

Specify behavior for origin validation.

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.
  • | (origin: string): boolean
  • | "same-origin"
  • | "none"

OutputFormat

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
"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.
"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";
  • | "ascii-math"
  • | "latex"
  • | "latex-expanded"
  • | "latex-unstyled"
  • | "math-json"
  • | "math-ml"
  • | "spoken"
  • | "spoken-text"
  • | "spoken-ssml"
  • | "spoken-ssml-with-highlighting"

ParseMode

The mode that indicates how a portion of content is interpreted

  • | "math"
  • | "text"
  • | "latex"

ParserErrorCode

Error code passed to the ErrorListener function.

See MathfieldOptions, convertLatexToMarkup
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.
  • | "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"

Range

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 from 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

[start: Offset, end: Offset]

Registers

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
  • medmuskip
  • thickmuskip
  • nulldelimiterspace
  • delimitershortfall
  • jot
Record<string, number | string | LatexValue>

Selection

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

direction: "forward" | "backward" | "none";
ranges: Range[];

Selector

Keys<Commands>

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
  • | "all"
  • | "selection"
  • | "left"
  • | "right"
  • | "group"
  • | "parent"

TabularEnvironment

  • | "array"
  • | "equation"
  • | "equation*"
  • | "subequations"
  • | "multline"
  • | "align"
  • | "align*"
  • | "aligned"
  • | "eqnarray"
  • | "split"
  • | "gather"
  • | "gathered"
  • | "lines"
  • | "multline"
  • | "multline*"
  • | "cases"
  • | "dcases"
  • | "rcases"
  • | "smallmatrix"
  • | "smallmatrix*"
  • | CasesEnvironment
  • | MatrixEnvironment

Token

string

Variant

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 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

  • | "ams"
  • | "double-struck"
  • | "calligraphic"
  • | "script"
  • | "fraktur"
  • | "sans-serif"
  • | "monospace"
  • | "normal"
  • | "main"
  • | "math"

VariantStyle

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
  • | "up"
  • | "bold"
  • | "italic"
  • | "bolditalic"
  • | ""

VirtualKeyboardLayout

VirtualKeyboardLayoutCore

displayEditToolbar: boolean;

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

displayShiftedKeycaps: boolean;

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

id: string;

A unique string identifying the layout

label: string;

A human readable string displayed in the layout switcher toolbar

labelClass: string;
tooltip: string;

A human readable tooltip associated with the label

VirtualKeyboardMessage

VirtualKeyboardMessageAction

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

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.
  • | "auto"
  • | "manual"
  • | "sandboxed"

module mathliveFunctions

Converting

Rendering

Other

Converting

convertLatexToMarkup()

convertLatexToMarkup(text, options?)
text: string

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

options?:
format: string;
letterShapeStyle: "tex" | "iso" | "french" | "upright";
mathstyle: "displaystyle" | "textstyle";

If "displaystyle" the “display” mode of TeX is used to typeset the formula, which is most appropriate for formulas that are displayed in a standalone block.

If "textstyle" is used, the “text” mode of TeX is used, which is most appropriate when displaying math “inline” with other text (on the same line).

→ string

Convert a LaTeX string to a string of HTML markup.

Note

This function does not interact with the DOM. The function does not load fonts or inject stylesheets in the document. It can 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" />

convertLatexToMathMl()

convertLatexToMathMl(latex, options)
latex: string

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

options:
generateID: boolean;
→ string

Convert a LaTeX string to a string of MathML markup.

convertLatexToSpeakableText()

convertLatexToSpeakableText(latex)
latex: string

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

→ string

The spoken representation of the input LaTeX.

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

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

Rendering

renderMathInDocument()

renderMathInDocument(options?: AutoRenderOptions): 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()

import { renderMathInDocument } from 'https://unpkg.com/mathlive?module';
if (window.readyState === "loading")
 document.addEventListener("DOMContentLoaded", () => renderMathInDocument());
else
  renderMathInDocument();

renderMathInElement()

renderMathInElement(element, options?)
element:
  • | string
  • | HTMLElement

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

options?: AutoRenderOptions

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

import { renderMathInElement } from 'https://unpkg.com/mathlive?module';
if (window.readyState === "loading")
 document.addEventListener("DOMContentLoaded", () => renderMathInElement("formula"));
else
  renderMathInElement("formula");

Other

convertAsciiMathToLatex()

convertAsciiMathToLatex(ascii: string): string

convertLatexToAsciiMath()

convertLatexToAsciiMath(latex: string, parseMode: ParseMode): string

globalMathLive()

globalMathLive(): MathLiveGlobal

makeSharedVirtualKeyboard()

makeSharedVirtualKeyboard(): VirtualKeyboardInterface
deprecated

This function is deprecated and is no longer necessary: the virtual keyboard is always shared. This function will be removed in a future release of MathLive.

To access the global shared virtual keyboard use window.mathVirtualKeyboard

serializeMathJsonToLatex()

serializeMathJsonToLatex(json: Expression): string

setKeyboardLayout()

setKeyboardLayout(name: "auto" | KeyboardLayoutName): 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.

setKeyboardLayoutLocale()

setKeyboardLayoutLocale(locale: string): 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.

validateLatex()

validateLatex(s: string): LatexSyntaxError[]
Documentation built with grok