Return an array of LaTeX syntax errors, if 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';
The content of the mathfield as a LaTeX expression.
document.querySelector('mf').value = '\\frac{1}{\\pi}'
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".
Return a textual representation of the content of the mathfield.
Optionalformat: OutputFormatThe 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"
Return the value of the mathfield from start to end
Optionalformat: OutputFormatReturn the value of the mathfield in range
Optionalformat: OutputFormatInternalOptionalformat: OutputFormatInsert 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.
Optionaloptions: InsertOptionsSet the content of the mathfield to the text interpreted as a LaTeX expression.
Optionalvalue: stringOptionaloptions: InsertOptionsTeX registers represent "variables" and "constants".
Changing the values of some registers can modify the layout of math expressions.
The following registers might be of interest:
thinmuskip: space between items of math listsmedmuskip: space between binary operationsthickmuskip: space between relational operatorsnulldelimiterspace: minimum space to leave blank in delimiter constructions, for example around a fractiondelimitershortfall: maximum space to overlap adjacent elements when a delimiter is too shortjot: space between lines in an array, or between rows in a multiline constructarraycolsep: space between columns in an arrayarraystretch: factor by which to stretch the height of each row in an arrayTo modify a register, use:
mf.registers.arraystretch = 1.5;
mf.registers.thinmuskip = { dimension: 2, unit: "mu" };
mf.registers.medmuskip = "3mu";
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*}`;
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}}.
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.
StaticfractionWhen using the keyboard to navigate a fraction, the order in which the numerator and navigator are traversed:
Default: "numerator-denominator"
StaticdecimalThe 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:
, key is pressed (if decimalSeparator is
",", the {,} LaTeX string is inserted when following some digits)Default: "."
StaticlocaleThe locale (language + region) to use for string localization.
If none is provided, the locale of the browser is used.
StaticstringsAn object whose keys are a locale string, and whose values are an object of string identifier to localized string.
Example
mf.strings = {
"fr-CA": {
"tooltip.undo": "Annuler",
"tooltip.redo": "Refaire",
}
}
If the locale is already supported, this will override the existing strings. If the locale is not supported, it will be added.
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);
Optionaloptions: Partial<MathfieldOptions>ReadonlyaccessReadonlyassignedReadonlyATTRIBUTE_ReadonlyattributesReadonlyattributeReadonlybaseURIReturns node's node document's document base URL.
ReadonlyCDATA_node is a CDATASection node.
ReadonlychildReadonlychildReturns the children.
ReadonlychildrenReturns the child elements.
Returns the value of element's class content attribute. Can be set to change it.
ReadonlyclientReadonlyclientReadonlyclientReadonlyclientReadonlyCOMMENT_node is a Comment node.
ReadonlycurrentCSSZoomReadonlydatasetReadonlyDOCUMENT_node is a DocumentFragment node.
ReadonlyDOCUMENT_node is a document.
ReadonlyDOCUMENT_Set when other is a descendant of node.
ReadonlyDOCUMENT_Set when other is an ancestor of node.
ReadonlyDOCUMENT_Set when node and other are not in the same tree.
ReadonlyDOCUMENT_Set when other is following node.
ReadonlyDOCUMENT_ReadonlyDOCUMENT_Set when other is preceding node.
ReadonlyDOCUMENT_node is a doctype.
ReadonlyELEMENT_node is an element.
ReadonlyENTITY_ReadonlyENTITY_ReadonlyfirstReturns the first child.
ReadonlyfirstReturns the first child that is an element, and null otherwise.
Returns the value of element's id content attribute. Can be set to change it.
ReadonlyisReturns true if node is connected and false otherwise.
ReadonlyisReadonlylastReturns the last child.
ReadonlylastReturns the last child that is an element, and null otherwise.
ReadonlylocalReturns the local name.
ReadonlynamespaceURIReturns the namespace.
ReadonlynextReturns the first following sibling that is an element, and null otherwise.
ReadonlynextReturns the next sibling.
ReadonlynodeReturns a string appropriate for the type of node.
ReadonlynodeReturns the type of node.
OptionalnonceReadonlyNOTATION_ReadonlyoffsetReadonlyoffsetReadonlyoffsetReadonlyoffsetReadonlyoffsetFires when the user aborts the download.
Fires when the object loses the input focus.
Occurs when playback is possible, but would require further buffering.
Fires when the contents of the object or selection have changed.
Fires when the user clicks the left mouse button on the object
Fires when the user clicks the right mouse button in the client area, opening the context menu.
Fires when the user double-clicks the object.
Fires on the source object continuously during a drag operation.
Fires on the source object when the user releases the mouse at the close of a drag operation.
Fires on the target element when the user drags the object to a valid drop target.
Fires on the target object when the user moves the mouse out of a valid drop target during a drag operation.
Fires on the target element continuously while the user drags the object over a valid drop target.
Fires on the source object when the user starts to drag a text selection or selected object.
Occurs when the duration attribute is updated.
Occurs when the media element is reset to its initial state.
Occurs when the end of playback is reached.
Fires when an error occurs during object loading.
Fires when the object receives focus.
Fires when the user presses a key.
Fires when the user presses an alphanumeric key.
Fires when the user releases a key.
Fires immediately after the browser loads the object.
Occurs when media data is loaded at the current playback position.
Occurs when the duration and dimensions of the media have been determined.
Occurs when Internet Explorer begins looking for media data.
Fires when the user clicks the object with either mouse button.
Fires when the user moves the mouse over the object.
Fires when the user moves the mouse pointer outside the boundaries of the object.
Fires when the user moves the mouse pointer into the object.
Fires when the user releases a mouse button while the mouse is over the object.
Occurs when playback is paused.
Occurs when the play method is requested.
Occurs when the audio or video has started playing.
Occurs to indicate progress while downloading media data.
Occurs when the playback rate is increased or decreased.
Fires when the user resets a form.
Fires when the user repositions the scroll box in the scroll bar on the object.
Occurs when the seek operation ends.
Occurs when the current playback position is moved.
Fires when the current selection changes.
Occurs when the download has stopped.
Occurs if the load operation has been intentionally halted.
Occurs to indicate the current playback position.
OptionalontouchcancelOptionalontouchendOptionalontouchmoveOptionalontouchstartOccurs when the volume is changed, or playback is muted or unmuted.
Occurs when playback stops because the next frame of a video resource is not available.
ReadonlyownerReturns the node document. Returns null for documents.
ReadonlyparentReturns the parent element.
ReadonlyparentReturns the parent.
ReadonlyprefixReturns the namespace prefix.
ReadonlypreviousReturns the first preceding sibling that is an element, and null otherwise.
ReadonlypreviousReturns the previous sibling.
ReadonlyPROCESSING_node is a ProcessingInstruction node.
ReadonlyscrollReadonlyscrollReadonlyshadowReturns element's shadow root, if any, and if shadow root's mode is "open", and null otherwise.
Returns the value of element's slot content attribute. Can be set to change it.
ReadonlytagReturns the HTML-uppercased qualified name.
ReadonlyTEXT_node is a Text node.
StaticcreateHTMLSupport 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.
StaticreadStaticspeakStaticversionAllows for manipulation of element's class content attribute as a set of whitespace-separated tokens through a DOMTokenList object.
InternalInternalInternalInternalInternalInternalInternalInternalInternalInternalInternalInternalInternalStaticcomputeA custom compute engine instance. If none is provided, a default one is
used. If null is specified, no compute engine is used.
StaticfontsA 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'
}
StaticformStaticisStaticobservedInternalCustom elements lifecycle hooks
StaticoptionsInternalPrivate lifecycle hooks. If adding a 'boolean' attribute, add its default value to getOptionsFromAttributes
StaticplonkSound played to provide feedback when a command has no effect, for example when pressing the spacebar at the root level.
The property is either:
soundsDirectory directoryStaticspeechIndicates 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
StaticspeechSets 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.
StaticspeechIndicates 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
StatictextThe 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]].
StatictextSpecify 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
StatictextA 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
Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.
The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.
When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.
When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.
When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.
If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.
The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.
Optionaloptions: boolean | AddEventListenerOptionsAppends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.
The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.
When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.
When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.
When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.
If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.
The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.
Optionaloptions: boolean | AddEventListenerOptionsInserts nodes just after node, while replacing strings in nodes with equivalent Text nodes.
Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.
Rest...nodes: (string | Node)[]Optionaloptions: number | KeyframeAnimationOptionsInserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes.
Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.
Rest...nodes: (string | Node)[]Creates a shadow root for element and returns it.
Inserts nodes just before node, while replacing strings in nodes with equivalent Text nodes.
Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.
Rest...nodes: (string | Node)[]Optionaloptions: CheckVisibilityOptionsReturns the first (starting at element) inclusive ancestor that matches selectors, and null otherwise.
Returns a bitmask indicating the position of other relative to node.
Returns true if other is an inclusive descendant of node, and false otherwise.
Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.
Execute a [[Commands|command]] defined by a selector.
mfe.executeCommand('add-column-after');
mfe.executeCommand(['switch-mode', 'math']);
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');
Optionaloptions: GetAnimationsOptionsReturns a HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classNames. The classNames argument is interpreted as a space-separated list of classes.
Optionaloptions: GetHTMLOptionsReturns node's root.
Optionaloptions: GetRootNodeOptionsInternalReturns whether node and otherNode have the same properties.
Inserts nodes before the first child of node, while replacing strings in nodes with equivalent Text nodes.
Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.
Rest...nodes: (string | Node)[]Returns the first element that is a descendant of node that matches selectors.
Returns all element descendants of node that match selectors.
Removes the event listener in target's event listener list with the same type, callback, and options.
Optionaloptions: boolean | EventListenerOptionsRemoves the event listener in target's event listener list with the same type, callback, and options.
Optionaloptions: boolean | EventListenerOptionsReplace all children of node with nodes, while replacing strings in nodes with equivalent Text nodes.
Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.
Rest...nodes: (string | Node)[]Replaces node with nodes, while replacing strings in nodes with equivalent Text nodes.
Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.
Rest...nodes: (string | Node)[]Displays element fullscreen and resolves promise when done.
When supplied, options's navigationUI member indicates whether showing navigation UI while in fullscreen is preferred or not. If set to "show", navigation simplicity is preferred over screen space, and if set to "hide", more screen space is preferred. User agents are always free to honor user preference over the application's. The default value "auto" indicates no application preference.
Optionaloptions: FullscreenOptionsOptionaloptions: PointerLockOptionsOptionaloptions: ScrollToOptionsOptionaloptions: ScrollToOptionsOptionalarg: boolean | ScrollIntoViewOptionsOptionaloptions: ScrollToOptionsIf force is not given, "toggles" qualifiedName, removing it if it is present and adding it if it is not present. If force is true, adds qualifiedName. If force is false, removes qualifiedName.
Returns true if qualifiedName is now present, and false otherwise.
Optionalforce: booleanStaticloadStaticplayReturn the id of the prompts matching the filter.
Optionalfilter: { Optionalcorrectness?: "undefined" | "correct" | "incorrect"Optionalid?: stringOptionallocked?: booleanReturn the content of the \placeholder{} command with the placeholderId
Optionalformat: OutputFormatThe bottom location of the caret (insertion point) in viewport coordinates.
See also [[setCaretPoint]]
The last valid offset.
The position of the caret/insertion point, from 0 to lastOffset.
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.
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.
Optionaloptions: { Optionalbias?: 0 | 1 | -1StatickeypressWhen a key on the virtual keyboard is pressed, produce a short haptic feedback, if the device supports it.
StatickeypressWhen 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 pressedreturn ... when the return/tab key is pressedspacebar ... when the spacebar is presseddefault ... 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.
StaticsoundsA 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.
The
MathfieldElementclass represent a DOM element that displays math equations. It is a subclass of the standardHTMLElementclass and as such inherits all of its properties and methods.It inherits many useful properties and methods from [[
HTMLElement]] such asstyle,tabIndex,addEventListener(),getAttribute(), etc...It is the main entry point to the MathLive library.
It is typically used to render a single equation. To render multiple equations, use multiple instances of
MathfieldElement. TheMathfieldElementclass provides special properties and methods to control the display and behavior of<math-field>elements.To create a new
MathfieldElement:The
MathfieldElementconstructor has an optional argument of [[MathfieldOptions]] to configure the element. The options can also be modified later:MathfieldElement CSS Variables
To customize the appearance of the mathfield, declare the following CSS variables (custom properties) in a ruleset that applies to the mathfield.
Alternatively you can set these CSS variables programatically:
--hue--contains-highlight-background-color--primary-color--text-font-family--smart-fence-opacity--smart-fence-colorYou can customize the appearance and zindex of the virtual keyboard panel with some CSS variables associated with a selector that applies to the virtual keyboard panel container.
Read more about customizing the virtual keyboard appearance
MathfieldElement CSS Parts
To style the virtual keyboard toggle, use the
virtual-keyboard-toggleCSS part. To use it, define a CSS rule with a::part()selector for example:MathfieldElement Attributes
An attribute is a key-value pair set as part of the tag:
The supported attributes are listed in the table below with their corresponding property.
The property can also be changed directly on the
MathfieldElementobject:The values of attributes and properties are reflected, which means you can change one or the other, for example:
An exception is the
valueproperty, which is not reflected on thevalueattribute: for consistency with other DOM elements, thevalueattribute remains at its initial value.disabledmf.disableddefault-modemf.defaultModeletter-shape-stylemf.letterShapeStylemin-font-scalemf.minFontScalepopover-policymf.popoverPolicymath-mode-spacemf.mathModeSpaceread-onlymf.readOnlyremove-extraneous-parenthesesmf.removeExtraneousParenthesessmart-fencemf.smartFencesmart-modemf.smartModesmart-superscriptmf.smartSuperscriptinline-shortcut-timeoutmf.inlineShortcutTimeoutscript-depthmf.scriptDepthvaluevaluemath-virtual-keyboard-policymathVirtualKeyboardPolicySee [[
MathfieldOptions]] for more details about these options.In addition, the following global attributes can also be used:
classdata-*hiddeniditem*styletabindexMathfieldElement Events
Listen to these events by using
addEventListener(). For events with additional arguments, the arguments are available inevent.detail.beforeinputinputevt.dataproperty includes a copy ofevt.inputType. SeeInputEventchangeselection-changemode-changemath,text) of the mathfield has changedundo-state-changeevt.detail.typeindicate if a snapshot was taken or an undo performed.read-aloud-status-changebefore-virtual-keyboard-toggleevt.detail.visibleproperty indicate if the keyboard will be visible or not. Listen for this event onwindow.mathVirtualKeyboardvirtual-keyboard-togglewindow.mathVirtualKeyboardgeometrychangeevt.detail.boundingRectproperty is the new bounding rectangle of the virtual keyboard. Listen for this event onwindow.mathVirtualKeyboardblurfocusmove-out`detail: {direction: 'forward'
keypressmountunmountKeywords
zindex, events, attribute, attributes, property, properties, parts, variables, css, mathfield, mathfieldelement