mathlive

The native keyboard event

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

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.

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

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.

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.

When true, the user cannot edit the mathfield.

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

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.

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.

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

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

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.

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.

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

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

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

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

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.

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:

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.

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

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

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

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.

Control the letter shape style:

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

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}

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

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

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.

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

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.

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

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

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

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.

See Guide: Speech

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

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

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

If the property is set to a string or HTMLAudioElement, 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 key 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, an HTMLAudioElement or null to supress the sound.

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

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

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

• '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.
• 'auto': 'onfocus' on touch-capable devices and 'off' otherwise (default).

The visual theme of 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).

Markup for the virtual keyboard toggle glyph.

If none is specified a default keyboard icon is used.

The right hand side toolbar configuration.

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

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.

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.

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

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

Default: 'tex2jax_ignore'

Custom LaTeX macros

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.

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;

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'

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

Default: 'math/tex'

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

Default: false

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'

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