mathlive

Modules

module "mathfield-element"

module "mathfield-element"class MathfieldElement

ExtendsHTMLElement

ImplementsMathfield

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 applied to the mathfield.

math-field {
 --hue: 10       // Set the highlight color and caret to a reddish hue
}
CSS VariableUsage
--hueHue of the highlight color and the caret
--highlightColor of the selection
--highlight-inactiveColor of the selection, when the mathfield is not focused
--caretColor of the caret/insertion point
--primaryPrimary accent color, used for example in the virtual keyboard
--text-font-familyThe font stack used in text mode
--keyboard-zindexThe z-index attribute of the virtual keyboard panel

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 locale="fr"></math-field>

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

The property can be changed either directly on the MathfieldElement object, or using setOptions() if it is prefixed with options., for example

 getElementById('mf').value = '\\sin x';
 getElementById('mf').setOptions({horizontalSpacingScale: 1.1});

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

getElementById('mf').setAttribute('virtual-keyboard-mode',  'manual');
console.log(getElementById('mf').getOption('virtualKeyboardMode'));
// Result: "manual"
getElementById('mf').setOptions({virtualKeyboardMode: 'onfocus');
console.log(getElementById('mf').getAttribute('virtual-keyboard-mode');
// Result: 'onfocus'

An exception is the value property, which is not reflected on the value attribute: the value attribute remains at its initial value.

AttributeProperty
disableddisabled
default-modeoptions.defaultMode
fonts-directoryoptions.fontsDirectory
horizontal-spacing-scaleoptions.horizontalSpacingScale
ignore-spacebar-in-math-modeoptions.ignoreSpacbarInMathMode
inline-shortcut-timeoutoptions.inlineShortcutTimeout
keypress-vibrationoptions.keypressVibration
letter-shape-styleoptions.letterShapeStyle
localeoptions.locale
read-onlyoptions.readOnly
remove-extraneous-parenthesesoptions.removeExtraneousParentheses
smart-fenceoptions.smartFence
smart-modeoptions.smartMode
smart-superscriptoptions.superscript
speech-engineoptions.speechEngine
speech-engine-rateoptions.speechEngineRate
speech-engine-voiceoptions.speechEngineVoice
text-to-speech-markupoptions.textToSpeechMarkup
text-to-speech-rulesoptions.textToSpeechRules
valuevalue
virtual-keyboard-layoutoptions.keyboardLayout
virtual-keyboard-modeoptions.keyboardMode
virtual-keyboard-themeoptions.keyboardTheme
virtual-keyboardsoptions.keyboards

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 availble in event.detail.

Event NameDescription
inputThe value of the mathfield has been modified. This happens on almost every keystroke in the mathfield.
changeThe user has commited the value of the mathfield. This happens when the user presses Return or leaves the mathfield.
selection-changeThe selection (or caret position) in the mathfield has changed
mode-changeThe mode (math, text) of the mathfield has changed
undo-state-changeThe state of the undo stack has changed
read-aloud-status-changeThe status of a read aloud operation has changed
virtual-keyboard-toggleThe visibility of the virtual keyboard panel has changed
blurThe mathfield is losing focus
focusThe mathfield is gaining focus
focus-outThe user is navigating out of the mathfield, typically using the keyboard
detail: {direction: 'forward' | 'backward' | 'upward' | 'downward'} cancellable
math-errorA parsing or configuration error happened
detail: ErrorListener<ParserErrorCode | MathfieldErrorCode>
keystrokeThe user typed a keystroke with a physical keyboard
detail: {keystroke: string, event: KeyboardEvent}
mountThe element has been attached to the DOM
unmountThe element is about to be removed from the DOM

class MathfieldElementnew MathfieldElement

To create programmatically a new mahfield 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('virtual-keyboard-layout', 'dvorak');
// ... or using `setOptions()`
mfe.setOptions({
virtualKeyboardMode: 'manual',
});
// Attach the element to the DOM
document.body.appendChild(mfe);

Accessing and changing the content

class MathfieldElementget/set value

value: string

The content of the mathfield as a Latex expression.

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

class MathfieldElementapplyStyle

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

If there is a selection, the style is applied to the selection

If the selection already has this style, it is removed.

If the selection has the style partially applied (i.e. only some sections), it is removed from those sections, and applied to the entire selection.

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

applyStyle(style: Style): void
style: Style

class MathfieldElementgetValue

getValue(format?: OutputFormat): string
format: OutputFormat
string

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

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

getValue(ranges: Range[], format?: OutputFormat): string
ranges: Range[]
format: OutputFormat
string

class MathfieldElementinsert

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

insert(s: string, options?: InsertOptions): boolean
s: string
options: InsertOptions
boolean

class MathfieldElementsetValue

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

Selection

class MathfieldElementget/set caretPoint

caretPoint: {x: number; y: number}

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

See also setCaretPoint

class MathfieldElementget lastPosition

lastPosition: number  read only

The last valid position.

class MathfieldElementget/set position

position: number

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

class MathfieldElementget/set selection

selection: Range[]

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 MathfieldElementselect

Select the content of the mathfield.

select(): void

class MathfieldElementsetCaretPoint

x and y are in viewport coordinates.

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

See also caretPoint

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

Other

class MathfieldElementget/set disabled

disabled: boolean

class MathfieldElementget/set mode

mode: ParseMode

class MathfieldElementexecuteCommand

Execute a Commands defined by a selector.

mfe.executeCommand('add-column-after');
mfe.executeCommand(['switch-mode', 'math']);
executeCommand(command: Selector | [Selector, any]): boolean
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

class MathfieldElementfind

Return an array of ranges matching the argument.

An array is always returned, but it has no element if there are no matching items.

find(latex: string): Range[]
latex: string
Range[]

Focus

class MathfieldElementblur

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

blur(): void

class MathfieldElementfocus

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

focus(): void

class MathfieldElementhasFocus

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

hasFocus(): boolean
boolean

Options

class MathfieldElementgetOption

getOption(key: extends keyof MathfieldOptions): MathfieldOptions[ extends keyof MathfieldOptions]
key: extends keyof MathfieldOptions
MathfieldOptions[ extends keyof MathfieldOptions]

class MathfieldElementgetOptions

getOptions(keys: extends keyof MathfieldOptions[]): Pick<MathfieldOptions, extends keyof MathfieldOptions>
keys: extends keyof MathfieldOptions[]
Pick<MathfieldOptions, extends keyof MathfieldOptions>

class MathfieldElementsetOptions

setOptions(options: Partial<MathfieldOptions>): void
options: Partial<MathfieldOptions>

module "mathfield-element"Types

module "mathfield-element"FocusOutEvent

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

The event detail.direction property indicates the direction the cursor was moving which can be useful to decide which element to focus next.

The event is cancelable, which will prevent the field from losing focus.

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

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

module "mathfield-element"KeystrokeEvent

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


event?: KeyboardEvent;

The native keyboard event

keystroke: string;

A string descring the keystroke, for example `“Alt-KeyU”. See W3C UIEvents for more information on the format of the descriptor.

module "mathfield-element"MathErrorEvent

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

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

after?: string;
arg?: string;
before?: string;
code: ParserErrorCode | MathfieldErrorCode;
latex?: string;

module "options"

module "options"Functions

module "options"setKeyboardLayout

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.

setKeyboardLayout(name: KeyboardLayoutName | "auto"): void
name:

module "options"setKeyboardLayoutLocale

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.

setKeyboardLayoutLocale(locale: string): void
locale: string

module "options"interface MathfieldHooks

These methods provide an opportunity to intercept or modify an action. Their return value indicate whether the default handling should proceed.

deprecated

Use corresponding events of MathfieldEvent instead


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

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

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

Return false to stop the handling of the event.

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

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

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

Return false to prevent the move, true to wrap around to the start of the field.

By default, the insertion point will wrap around.

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

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

direction indicates the direction of the navigation.

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

module "options"interface MathfieldListeners

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

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

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

deprecated

Use corresponding events of MathfieldEvent instead


onBlur: (sender: Mathfield): void

The mathfield has lost keyboard focus

onCommit: (sender: Mathfield): void
onContentDidChange: (sender: Mathfield): void
onContentWillChange: (sender: Mathfield): void
onFocus: (sender: Mathfield): void

The mathfield has gained keyboard focus

onModeChange: (sender: Mathfield, mode: ParseMode): void
onReadAloudStatus: (sender: Mathfield): void
onSelectionDidChange: (sender: Mathfield): void
onSelectionWillChange: (sender: Mathfield): void
onUndoStateDidChange: UndoStateChangeListener
onUndoStateWillChange: UndoStateChangeListener
onVirtualKeyboardToggle: (sender: Mathfield, visible: boolean, keyboardElement: HTMLElement): void

module "options"interface VirtualKeyboardKeycap

altKeys?: string

A named set of alternate keys to display when there is a long press on the key.

aside?: string

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

class?: string

CSS class to apply to the keycap.

command?: string

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

shifted?: string

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

shiftedCommand?: string

Command to perform when the shifted key is pressed

module "options"interface VirtualKeyboardLayer

backdrop?: string
container?: string
rows?: VirtualKeyboardKeycap[][]
styles?: string

module "options"Types

module "options"EditingOptions

ignoreSpacebarInMathMode: boolean;

When true and the spacebar is pressed, no space is inserted.

When false, a space is inserted when the spacebar is pressed.

readOnly: boolean;

When true, the user cannot edit the mathfield.

removeExtraneousParentheses: boolean;

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

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

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

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

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

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

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

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

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

The 'after' key, if present, indicate in what context (surrounding characters) the shortcut will apply. One or more values can be specified, separated by a ‘+’ sign. If any of the values match, the shortcut will be 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; mode?: ParseMode; value: string}

module "options"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: {[key: string]: InlineShortcutDefinition};

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

string | {after?: string; mode?: ParseMode; value: string}

overrideDefaultInlineShortcuts: boolean;
deprecated

deprecated

Use:

mf.setConfig(
     'inlineShortcuts',
     {   ...mf.getConfig('inlineShortcuts'),
         ...newShortcuts
     }
)

to add newShortcuts to the default ones

module "options"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 | [Selector, any];

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

ifMode?: ParseMode;

If specified, this indicates in which mode this keybinding will apply. If none is specified, the keybinding 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:

PlatformModifiers
macOS, iOSctrl, shift, alt, cmd
Windowsctrl, shift, alt, win
Linux, Android, ChromeOSctrl, 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:

  • az, 09
  • `, -, =, [, ], \, ;, ', ,, ., /
  • left, up, right, down, pageup, pagedown, end, home
  • tab, enter, escape, space, backspace, delete
  • f1f19
  • pausebreak, capslock, insert
  • numpad0numpad9, 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 az 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.

If a keybinding is invalid (impossible to produce) with the current keyboard layout, an error will be generated, and the onError listener will be called with a invalid-keybinding error code.

module "options"KeyboardLayoutName

See setKeyboardLayout.

NamePlatformDisplay name
'apple.en-intl'AppleEnglish (International)
'apple.french'AppleFrench (AZERTY)
'apple.german'AppleGerman (QWERTZ)
'windows.en-intl'WindowsEnglish (International)
'windows.french'WindowsFrench (AZERTY)
'windows.german'WindowsGerman (QWERTZ)
'linux.en'LinuxEnglish
'linux.french'LinuxFrench (AZERTY)
'linux.german'LinuxGerman (QWERTZ)

"apple.en-intl" | "apple.french" | "apple.german" | "apple.spanish" | "windows.en-intl" | "windows.french" | "windows.german" | "windows.spanish" | "linux.en" | "linux.french" | "linux.german" | "linux.spanish"

module "options"KeyboardOptions

keybindings: Keybinding[];

module "options"LayoutOptions

defaultMode: "math" | "text";
horizontalSpacingScale: number;

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

letterShapeStyle: "auto" | "tex" | "iso" | "french" | "upright";

Control the letter shape style:

letterShapeStylexyzABCαβɣΓΔΘ
isoitititit
texitititup
frenchitupupup
uprightupupupup

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

module "options"LocalizationOptions

locale: string;

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

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

strings: {[locale: string]: {[key: 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.

module "options"MathfieldConfig

deprecated

Use MathfieldOptions


module "options"MathfieldOptions


  • LayoutOptions &
  • EditingOptions &
  • LocalizationOptions &
  • InlineShortcutsOptions &
  • KeyboardOptions &
  • VirtualKeyboardOptions &
  • TextToSpeechOptions &
  • MathfieldHooks &
  • MathfieldListeners &
  • createHTML: (html: string): 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.

    fontsDirectory: 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’.

    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 top your website
         fontsDirectory: 'https://example.com/fonts'
    }
    
    namespace: string;
    deprecated

    Namespace that is added to data- attributes to avoid collisions with other libraries.

    The namespace should be a string of lowercase letters.

    It is empty by default.

    onError: ErrorListener<ParserErrorCode | MathfieldErrorCode>;

    An optional listener function that will be invoked when an error is encountered.

    This could be a Latex parsing error, for the initial value of the mathfield, a value inserted programmatically later, or through a user interaction (pasting in the mathfield for example). See ParserErrorCode for the list of possible parsing errors.

    This could also be another kind of error, such as an invalid keybinding.

    substituteTextArea: string | (): HTMLElement;

    This function provides the option of substituting the focusable DOM element used to capture keyboard input.

    An (invisible) DOM element is used to capture the keyboard events. By default, this element is a <textarea> on desktop and a <span> on mobile devices, to prevent the device virtual keyboard from being displayed.

    Alternatively, the ID of a DOM element can be provided.

module "options"TextToSpeechOptions

readAloudHook: (element: HTMLElement, text: string, config: MathfieldOptions): void;
speakHook: (text: string, config: Partial<MathfieldOptions>): void;
speechEngine: "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 speech example

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

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

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

textToSpeechRules: "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 speech example

textToSpeechRulesOptions: {[key: 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

module "options"UndoStateChangeListener

(target: Mathfield, action: "undo" | "redo" | "snapshot"): void

module "options"VirtualKeyboardOptions

customVirtualKeyboardLayers: {[layerName: string]: string | VirtualKeyboardLayer};

Some additional custom virtual keyboard layers.

A keyboard is made up of one or more layers (think of the main layer and the shift layer on a hardware keyboard). Each key in this object define a new keyboard layer (or replace an existing one). The value of the key should be some HTML markup.

See virtual keyboard example

customVirtualKeyboards: {[layerName: string]: string};
keypressSound: string | HTMLAudioElement| {default: string | HTMLAudioElement; delete?: string | HTMLAudioElement; return?: string | HTMLAudioElement; spacebar?: string | HTMLAudioElement};

When a key on the virtual keyboard is pressed, produce a short audio feedback. The value should be either a URL to a sound file or an object with the following keys:

  • delete URL to a sound file 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 key is required, the others are optional. If they are missing, this sound is played as well.
keypressVibration: boolean;

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

plonkSound?: string | HTMLAudioElement;

URL to a sound file which will be played to provide feedback when a command has no effect, for example when pressing the spacebar at the root level.

virtualKeyboardLayout: "auto" | "qwerty" | "azerty" | "qwertz" | "dvorak" | "colemak";
virtualKeyboardMode: "auto" | "manual" | "onfocus" | "off";
  • 'manual': pressing the virtual keyboard toggle button will show or hide the virtual keyboard. If hidden, the virtual keyboard is not shown when the field is focused until the toggle button is pressed.
  • 'onfocus': the virtual keyboard will be displayed whenever the field is focused and hidden when the field loses focus. In that case, the virtual keyboard toggle button is not displayed.
  • 'off': the virtual keyboard toggle button is not displayed, and the virtual keyboard is never triggered.

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

virtualKeyboardTheme: "material" | "apple" | "";

The visual theme used for the virtual keyboard.

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

virtualKeyboardToggleGlyph: string;

If specified, the markup to be used to display the virtual keyboard toggle glyph. If none is specified a default keyboard icon is used.

virtualKeyboards: "all" | "numeric" | "roman" | "greek" | "functions" | "symbols" | "command" | string;

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

The keyboards will be displayed in the order indicated.

module "mathlive"

Use MathLive to render and edit mathematical formulas.

Read Getting Started for more info.

<script type="module">
// Load the `Mathlive` module from a CDN
import { convertLatexToSpeakableText } from 'https://unpkg.com/mathlive/dist/mathlive.min.mjs';

console.log(convertLatexToSpeakableText('e^{i\\pi}+1=0'));
</script>

version

module "mathlive"Functions

Converting

Rendering

Other

Converting

module "mathlive"astToLatex

Converts a MathJSON Abstract Syntax Tree to a LaTeX string.

See Also: latexToAST()

deprecated

Use MathJSON

deprecated
astToLatex(mathJson: any, options?: {beginRepeatingDigits?: string; decimalMarker?: string; endRepeatingDigits?: string; exponentMarker?: string; exponentProduct?: string; groupSeparator?: string; precision?: number; product?: string}): string
mathJson: any
options:
beginRepeatingDigits?: string;

The format used for numbers using the scientific notation. Default = "auto" * / scientificNotation?: ‘auto’ | ‘engineering’ | ‘on’; /** The string used at the begining of repeating digits. Default = "\\overline{"

decimalMarker?: string;

The character used as the decimal marker. Default = ".".

endRepeatingDigits?: string;

The string used at the end of repeating digits. Default = "}"

exponentMarker?: string;

The character used to indicate an exponent. Default = ""

exponentProduct?: string;

The character used before an exponent indicator. Default = "\\cdot "

groupSeparator?: string;

The character used to separate group of numbers, typically thousands. Default = "\\, "

precision?: number;

The number of digits used in the representation of numbers. Default = 14

product?: string;

The character used to indicate product. Other option would be "\\times ". Default = "\\cdot "

string

The LaTeX representation of the Abstract Syntax Tree, if valid.

module "mathlive"convertLatexToMarkup

Convert a LaTeX string to a string of HTML markup.

Note

This function does not interact with the DOM. It can be used on the server side. The function does not load fonts or inject stylesheets in the document. 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" />
convertLatexToMarkup(text: string, options?: {letterShapeStyle?: "tex" | "french" | "iso" | "upright" | "auto"; macros?: MacroDictionary; mathstyle?: "displaystyle" | "textstyle"; onError?: ErrorListener<ParserErrorCode>}): string
text: string

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

options:
letterShapeStyle?: "tex" | "french" | "iso" | "upright" | "auto";
macros?: MacroDictionary;

A dictionary of LaTeX macros

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

onError?: ErrorListener<ParserErrorCode>;

A function invoked when a syntax error is encountered. An attempt to recover will be made even when an error is reported.

string

module "mathlive"convertLatexToMathMl

Convert a LaTeX string to a string of MathML markup.

convertLatexToMathMl(latex: string, options?: {generateID: boolean; macros?: MacroDictionary; onError?: ErrorListener<ParserErrorCode>}): string
latex: string

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

options:
generateID: boolean;
macros?: MacroDictionary;
onError?: ErrorListener<ParserErrorCode>;

Callback invoked when an error is encountered while parsing the input string.

string

module "mathlive"convertLatexToSpeakableText

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

console.log(convertLatexToSpeakableText('\\frac{1}{2}'));
// 'half'
convertLatexToSpeakableText(latex: string, options: TextToSpeechOptions & {macros?: MacroDictionary; onError?: ErrorListener<ParserErrorCode>}): string
latex: string

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

options:
readAloudHook: (element: HTMLElement, text: string, config: MathfieldOptions): void;
speakHook: (text: string, config: Partial<MathfieldOptions>): void;
speechEngine: "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 speech example

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

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

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

textToSpeechRules: "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 speech example

textToSpeechRulesOptions: {[key: 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

string

The spoken representation of the input LaTeX.

module "mathlive"latexToAST

Convert a LaTeX string to a MathJSON Abstract Syntax Tree

See Also: astToLatex()

deprecated

Use MathJSON

deprecated
latexToAST(latex: string, options?: {macros?: MacroDictionary; onError?: ErrorListener<ParserErrorCode | string>}): any
latex: string

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

options:
macros?: MacroDictionary;

A dictionary of LaTeX macros

onError?: ErrorListener<ParserErrorCode | string>;

Callback invoked when an error is encountered while parsing the input string.

any

The Abstract Syntax Tree as an object literal using the MathJSON format.

module "mathlive"latexToMarkup

deprecated

Use convertLatexToMarkup

deprecated
latexToMarkup(text: string, options?: {letterShapeStyle?: "tex" | "french" | "iso" | "upright" | "auto"; macros?: MacroDictionary; mathstyle?: "displaystyle" | "textstyle"; onError?: ErrorListener<ParserErrorCode>}): string
text: string
options:
letterShapeStyle?: "tex" | "french" | "iso" | "upright" | "auto";
macros?: MacroDictionary;
mathstyle?: "displaystyle" | "textstyle";
onError?: ErrorListener<ParserErrorCode>;
string

module "mathlive"latexToMathML

deprecated

Use convertLatexToMathMl

deprecated
latexToMathML(latex: string, options?: {generateID: boolean; macros?: MacroDictionary; onError?: ErrorListener<ParserErrorCode>}): string
latex: string
options:
generateID: boolean;
macros?: MacroDictionary;
onError?: ErrorListener<ParserErrorCode>;
string

module "mathlive"latexToSpeakableText

deprecated

Use convertLatexToSpeakableText

deprecated
latexToSpeakableText(latex: string, options: TextToSpeechOptions & {macros?: MacroDictionary; onError?: ErrorListener<ParserErrorCode>}): string
latex: string
options:
string

Rendering

module "mathlive"getOriginalContent

After calling renderMathInElement or makeMathField the original content can be retrieved by calling this function.

Given the following markup:

<span id='equation'>$f(x)=sin(x)$</span>

The following code:

renderMathInElement('equation');
console.log(getOriginalContent('equation'));

will output:

$f(x)=sin(x)$
deprecated
getOriginalContent(element: string | HTMLElement, options?: {namespace?: string}): string
element:

A DOM element ID, a DOM element or a Mathfield.

options:
namespace?: string;

The namespace used for the data- attributes. If you used a namespace with renderMathInElement(), you must use the same namespace here.

string

module "mathlive"renderMathInDocument

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

Read Getting Started.

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

module "mathlive"renderMathInElement

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

Read Getting Started.

renderMathInElement(element: string | HTMLElement, options?: AutoRenderOptions): void
element:

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

options: AutoRenderOptions

module "mathlive"revertToOriginalContent

After calling renderMathInElement or makeMathField the original content can be restored by calling this function.

deprecated
revertToOriginalContent(element: HTMLElement, options?: {namespace?: string}): void
element: HTMLElement
options:
namespace?: string;

Other

module "mathlive"makeMathField

Convert a DOM element into an editable mathfield.

Consider using a <math-field> tag or new MathfieldElement() instead. {.notice–warning}

The mathfield property of the DOM element is a reference to the corresponding Mathfield object. This value is also returned by makeMathField().

deprecated

Use new <a href="#MathfieldElement">MathfieldElement</a>()

deprecated
makeMathField(element: HTMLElement | string, options: MathfieldOptions): Mathfield
element:

A DOM element, for example as obtained by document.getElementById(), or the ID of a DOM element as a string.

Given the HTML markup:

<span id='equation'>$f(x)=sin(x)$</span>

The following code will turn the span into an editable mathfield.

import { makeMathField } from 'https://unpkg.com/mathlive/dist/mathlive.min.mjs';
makeMathField('equation');
options: MathfieldOptions
Mathfield

module "mathlive"version

version: 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 "mathlive"AutoRenderOptions

TeX?: {delimiters?: {display: string[][]; inline: string[][]}; processEnvironments?: boolean};
createHTML?: (html: string): any;

Support for Trusted Type.

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

fontsDirectory?: 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’.

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 top your website
     fontsDirectory: 'https://example.com/fonts'
}
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'

macros?: MacroDictionary;

Custom LaTeX macros

namespace?: string;

Namespace that is added to data- attributes to avoid collisions with other libraries.

It is empty by default.

The namespace should be a string of lowercase letters.

preserveOriginalContent?: boolean;

If true, store the original textual content of the element in a data-original-content attribute. This value can be accessed for example to restore the element to its original value:

     elem.innerHTML = elem.dataset.originalContent;
deprecatd
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'

processScriptType?: string;

<script> tags of the indicated type will be processed while others will be ignored.

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: ['noscript', 'style', 'textarea', 'pre', 'code', 'annotation', 'annotation-xml']

module "mathfield"

module "mathfield"interface Mathfield

Implemented byMathfieldElement

Accessing the Content

Changing the Content

Focus

Other

Accessing the Content

interface Mathfield$latex

Sets or gets the content of the mathfield.

If text is not empty, sets the content of the mathfield to the text interpreted as a LaTeX expression.

If text is empty (or omitted), return the content of the mathfield as a LaTeX expression.

deprecated

Use setValue and getValue

deprecated
$latex(text?: string, options?: InsertOptions): string
text: string
options: InsertOptions
string

interface Mathfield$selectedText

Returns a textual representation of the selection in the mathfield.

deprecated

Use mfe.getValue(mfe.getSelection())

deprecated
$selectedText(format?: OutputFormat): string
format: OutputFormat

The format of the result. Default = "latex"

string

interface MathfieldgetValue

Returns a textual representation of the mathfield.

getValue(format?: OutputFormat): string
format: OutputFormat

The format of the result. Default = "latex"

string

interface MathfieldsetValue

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

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

Changing the Content

interface Mathfield$keystroke

deprecated

Use executeCommand or setValue

deprecated
$keystroke(keys: string, evt?: KeyboardEvent): boolean
keys: string

A string representation of a key combination.

For example "Alt-KeyU".

See W3C UIEvents for more information on the format of the descriptor.

evt: KeyboardEvent

An event corresponding to the keystroke. Pass this event if the keystroke originated from a user interaction that produced it. If the keystroke is synthetic (for example, triggered in response to a click or other event not involving a keyboard), omit it.

boolean

Return true if the field need to be re-rendered

interface Mathfield$typedText

Simulates a user typing the keys indicated by text.

deprecated

Use executeCommand or setValue

deprecated
$typedText(text: string): void
text: string

A sequence of one or more characters.

interface Mathfieldinsert

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

insert(s: string, options?: InsertOptions): boolean
s: string
options: InsertOptions
boolean

Focus

interface Mathfield$blur

deprecated

Use blur

deprecated
$blur(): void

interface Mathfield$focus

deprecated

Use focus

deprecated
$focus(): void

interface Mathfield$hasFocus

deprecated

Use hasFocus

deprecated
$hasFocus(): boolean
boolean

interface Mathfieldblur

blur(): void

interface Mathfieldfocus

focus(): void

interface MathfieldhasFocus

hasFocus(): boolean
boolean

Other

interface Mathfield$applyStyle

deprecated

Use applyStyle

deprecated
$applyStyle(style: Style): void
style: Style

interface Mathfield$clearSelection

deprecated

Use executeCommand

deprecated
$clearSelection(): void

interface Mathfield$el

Return the DOM element associated with this mathfield.

Note that this.$el().mathfield === this

deprecated
HTMLElement

interface Mathfield$insert

deprecated

Use insert

deprecated
$insert(s: string, options?: InsertOptions): boolean
s: string
options: InsertOptions
boolean

interface Mathfield$perform

deprecated

Use executeCommand

deprecated
$perform(command: Selector | [Selector, any]): boolean
command:
boolean

interface Mathfield$revertToOriginalContent

Reverts this mathfield to its original content.

After this method has been called, no other methods can be called on the object.

To turn the element back into a mathfield, call makeMathField() on the element again to get a new mathfield object.

deprecated
$revertToOriginalContent(): void

interface Mathfield$select

deprecated

Use select

deprecated
$select(): void

interface Mathfield$selectionAtEnd

Checks if the selection extends to the end of the selection group.

deprecated
$selectionAtEnd(): boolean
boolean

interface Mathfield$selectionAtStart

Checks if the selection starts at the beginning of the selection group.

deprecated
$selectionAtStart(): boolean
boolean

interface Mathfield$selectionDepth

Returns the depth of the selection group.

If the selection is at the root level, returns 0.

If the selection is a portion of the numerator of a fraction which is at the root level, return 1. Note that in that case, the numerator would be the “selection group”.

deprecated

Use mfe.selection[0].depth

deprecated
$selectionDepth(): number
number

interface Mathfield$selectionIsCollapsed

Checks if the selection is collapsed.

deprecated

Use mfe.selection[0].collapsed

deprecated
$selectionIsCollapsed(): boolean
boolean

True if the length of the selection is 0, that is, if it is a single insertion point.

interface Mathfield$text

deprecated

Use getValue

deprecated
$text(format?: OutputFormat): string
format: OutputFormat
string

interface MathfieldapplyStyle

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

If there is a selection, the style is applied to the selection

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

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

applyStyle(style: Style): void
style: Style

interface MathfieldexecuteCommand

Execute a Commands defined by a selector.

mfe.executeCommand('add-column-after');
mfe.executeCommand(['switch-mode', 'math']);
executeCommand(command: Selector | [Selector, any]): boolean
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

interface Mathfieldfind

find(latex: string): Range[]
latex: string
Range[]

interface MathfieldgetCaretPoint

getCaretPoint(): {x: number; y: number} | null
{x: number; y: number} | null

interface MathfieldgetConfig

deprecated

Use getOptions

deprecated
getConfig(keys: extends keyof MathfieldOptions[]): Pick<MathfieldOptions, extends keyof MathfieldOptions>
keys: extends keyof MathfieldOptions[]
Pick<MathfieldOptions, extends keyof MathfieldOptions>

deprecated
getConfig(key: extends keyof MathfieldOptions): MathfieldOptions[ extends keyof MathfieldOptions]
key: extends keyof MathfieldOptions
MathfieldOptions[ extends keyof MathfieldOptions]

deprecated
getConfig(): MathfieldOptions
MathfieldOptions

interface MathfieldgetOption

getOption(key: extends keyof MathfieldOptions): MathfieldOptions[ extends keyof MathfieldOptions]
key: extends keyof MathfieldOptions
MathfieldOptions[ extends keyof MathfieldOptions]

interface MathfieldgetOptions


getOptions(keys: extends keyof MathfieldOptions[]): Pick<MathfieldOptions, extends keyof MathfieldOptions>
keys: extends keyof MathfieldOptions[]
Pick<MathfieldOptions, extends keyof MathfieldOptions>

interface Mathfieldselect

select(): void

interface MathfieldsetCaretPoint

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

interface MathfieldsetConfig

deprecated

Use setOptions

deprecated
setConfig(options: Partial<MathfieldOptions>): void
options: Partial<MathfieldOptions>

interface MathfieldsetOptions

setOptions(options: Partial<MathfieldOptions>): void
options: Partial<MathfieldOptions>

interface MathfieldMathfield.mode

ParseMode

module "mathfield"interface Model

mathfield: Mathfield

module "mathfield"interface Range

A pair of boundary points that can be used to denote a fragment of an expression such as the selection.

A range can be collapsed (empty) in which case it points to a single location in an expression and its content is empty.

A range 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 selectionis 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


collapsed?: boolean

True when start === end, that is an empty range with no content, a single insertion point.

depth?: number

The depth of the common ancestor of the start and end offsets.

Depth starts at 0 and increase for each fraction, root, superscript and subscript.

direction?: "forward" | "backward" | "none"
end?: number

An offset indicating where the range ends.

end should be greater than or equal to start

start: number

An offset indicating where the range starts.

0 is the first possible offset.

module "mathfield"Types

module "mathfield"InsertOptions

feedback?: boolean;

If true, provide audio and haptic feedback

focus?: boolean;

If true, the mathfield will be focused after the insertion

format?: string;

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";
macros?: MacroDictionary;
mode?: ParseMode | "auto";

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

placeholder?: string;
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.

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
smartFence?: boolean;

If true, promote plain fences, e.g. (, as \left...\right or \mleft...\mright

style?: Style;
suppressChangeNotifications?: boolean;

module "mathfield"OutputFormat

FormatDescription
"latex"LaTeX rendering of the content, with LaTeX macros not expanded
"latex-expanded"All macros are recursively expanded to their definition
"json"A MathJSON abstract syntax tree, as an object literal formated as a JSON string
"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-withHighlighting"Like "spoken-ssml" but with additional annotations necessary for synchronized higlighting (read aloud)
"mathML"A string of MathML markup

"latex" | "latex-expanded" | "mathjson" | "json" | "json-2" | "spoken" | "spoken-text" | "spoken-ssml" | "spoken-ssml-withHighlighting" | "mathML" | "ASCIIMath"

module "commands"

module "commands"interface Commands

Commands return true if they resulted in a dirty state

Array

Auto-complete

Clipboard

Deleting

Scrolling

Selection

Undo/Redo

Virtual Keyboard

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

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

executeCommand("deleteNextChar"): boolean

interface Commandscommand​deleteNextWord

executeCommand("deleteNextWord"): boolean

interface Commandscommand​deletePreviousChar

executeCommand("deletePreviousChar"): 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

Scrolling

interface Commandscommand​scrollIntoView

executeCommand("scrollIntoView"): boolean

interface Commandscommand​scrollToEnd

executeCommand("scrollToEnd"): boolean

interface Commandscommand​scrollToStart

executeCommand("scrollToStart"): boolean

Selection

interface Commandscommand​extendDown

executeCommand("extendDown"): 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​extendToNextChar

executeCommand("extendToNextChar"): boolean

interface Commandscommand​extendToNextWord

executeCommand("extendToNextWord"): boolean

interface Commandscommand​extendToPreviousBoundary

executeCommand("extendToPreviousBoundary"): boolean

interface Commandscommand​extendToPreviousChar

executeCommand("extendToPreviousChar"): boolean

interface Commandscommand​extendToPreviousWord

executeCommand("extendToPreviousWord"): boolean

interface Commandscommand​extendUp

executeCommand("extendUp"): 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

Virtual Keyboard

interface Commandscommand​hideVirtualKeyboard

executeCommand("hideVirtualKeyboard"): boolean

interface Commandscommand​showVirtualKeyboard

executeCommand(["showVirtualKeyboard", theme: "apple" | "material" | ""]): boolean
theme: "apple" | "material" | ""

interface Commandscommand​toggleVirtualKeyboard

executeCommand(["toggleVirtualKeyboard", theme: "apple" | "material" | ""]): boolean
theme: "apple" | "material" | ""

Other

interface Commandscommand​applyStyle

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

interface Commandscommand​commit

executeCommand("commit"): boolean

interface Commandscommand​enterCommandMode

executeCommand("enterCommandMode"): boolean

deprecated

The command mode will be dropped in a future release.

interface Commandscommand​insert

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

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​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).

module "commands"Types

module "commands"Selector

Keys<Commands>

module "commands"SpeechScope

How much of the formula should be spoken:

allthe entire formula
selectionthe selection portion of the formula
leftthe element to the left of the selection
rightthe element to the right of the selection
groupthe group (numerator, root, etc…) the selection is in
parentthe parent of the selection

"all" | "selection" | "left" | "right" | "group" | "parent"

module "core"

module "core"interface Style

backgroundColor?: string
color?: string
cssClass?: string
cssId?: string
fontFamily?: string
fontSeries?: FontSeries
fontShape?: FontShape
fontSize?: string
isPhantom?: boolean
letterShapeStyle?: "tex" | "french" | "iso" | "upright" | "auto"
mode?: ParseMode | string
variant?: Variant
variantStyle?: VariantStyle

module "core"Types

module "core"ErrorListener

<T> = (err: {after?: string; arg?: string; before?: string; code: ; latex?: string}): void

module "core"FontSeries

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

module "core"FontShape

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

module "core"MacroDefinition

See Also


args?: number;
def: string;

module "core"MacroDictionary

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

For example:

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

The code above will support the following notation:

\smallfrac{5}{16}

See Also


[name: string]: string | MacroDefinition

module "core"MathfieldErrorCode

"invalid-keybinding" | "font-not-found"

module "core"ParseMode

The mode that indicates how a portion of content is interpreted


"math" | "text" | "command" | "chem"

module "core"ParserErrorCode

Error code passed to the ErrorListener function.

See MathfieldOptions, convertLatexToMarkup

font-not-foundA required font could not be loaded. The fontDirectory option may not be setup correctly or the ‘fonts’ directory is missing.
invalid-keybindingA keybinding includes a combinatino of keys which cannot be performed with the current keyboard layout.
unknown-commandThere is no definition available for this command, e.g. \zin
unknown-environmentThere is no definition available for this environment, e.g. \begin{foo}
invalid-commandThis command is not valid in the current mode (e.g. text command in math mode)
unbalanced-bracesThere are too many or too few { or }
unbalanced-environmentAn environment was open but never closed (\begin{array}) or the \end command does not match the \begin command (\begin{array*}\end{array})
unbalanced-mode-shiftA $, $, \( or \[ was not balanced
missing-argumentA required argument is missing, e.g. \frac{2}
too-many-infix-commandsA group can include only one infix command (i.e. \choose, \atop). In general it’s best to avoid infix commands.
unexpected-command-in-stringA command expected a string argument, but there was a command instead
missing-unitAn argument requiring a dimension was missing an unit.
unexpected-delimiterAn invalid symbol or command was used as a delimiter.
unexpected-tokenAn unexpected character was encountered.
unexpected-end-of-stringThe end of the string was reached, but some required arguments were missing.
improper-alphabetic-constantThe 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"

module "core"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 (roman) 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 completely equivalent to a main variant with italic variant style applied.

See Also


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

module "core"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.

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

"up" | "bold" | "italic" | "bolditalic" | ""
Documentation built with grok