API Methods¶

To use the MathQuill API, first get the latest version of the interface:

var MQ = MathQuill.getInterface(2);

By default, MathQuill overwrites the global MathQuill variable when loaded. If you do not want this behavior, you can use .noConflict() (similar to jQuery.noConflict()):

<script src="/path/to/first-mathquill.js"></script>
<script src="/path/to/second-mathquill.js"></script>
<script>
var secondMQ = MathQuill.noConflict().getInterface(2);
secondMQ.MathField(...);

var firstMQ = MathQuill.getInterface(2);
firstMQ.MathField(...);
</script>

This lets different copies of MathQuill each power their own math fields, but using different copies on the same DOM element won't work. .noConflict() is primarily intended to help you reduce globals.

Constructors¶

MQ.StaticMath(html_element)¶

Creates a non-editable MathQuill initialized with the contents of the HTML element and returns a StaticMath object.

If the given element is already a static math instance, this will return a new StaticMath object with the same .id. If the element is a different type of MathQuill, this will return null.

MQ.MathField(html_element, [ config ])¶

Creates an editable MathQuill initialized with the contents of the HTML element and returns a MathField object.

If the given element is already an editable math field, this will return a new editable MathField object with the same .id. If the element is a different type of MathQuill, this will return null.

\MathQuillMathField LaTeX command¶

\MathQuillMathField can be used to embed editable math fields inside static math, like:

<span id="fill-in-the-blank">\sqrt{ \MathQuillMathField{x}^2 + \MathQuillMathField{y}^2 }</span>
<script>
  var fillInTheBlank = MQ.StaticMath(document.getElementById('fill-in-the-blank'));
  fillInTheBlank.innerFields[0].latex() // => 'x'
  fillInTheBlank.innerFields[1].latex() // => 'y'
</script>

As you can see, they can be accessed on the StaticMath object via .innerFields.

MQ(html_element)¶

MQ itself is a function that takes an HTML element and, if it's the root HTML element of a static math or math field, returns an API object for it (if not, null):

MQ(mathFieldSpan) instanceof MQ.MathField // => true
MQ(otherSpan) // => null

MQ.config(config)¶

Updates the global configuration options (which can be overridden on a per-field basis).

Comparing MathFields¶

Checking Type¶

var staticMath = MQ.StaticMath(staticMathSpan);
mathField instanceof MQ.StaticMath // => true
mathField instanceof MQ // => true
mathField instanceof MathQuill // => true

var mathField = MQ.MathField(mathFieldSpan);
mathField instanceof MQ.MathField // => true
mathField instanceof MQ.EditableField // => true
mathField instanceof MQ // => true
mathField instanceof MathQuill // => true

Comparing IDs¶

API objects for the same MathQuill instance have the same .id, which will always be a unique truthy primitive value that can be used as an object key (like an ad hoc Map or Set):

MQ(mathFieldSpan).id === mathField.id // => true

var setOfMathFields = {};
setOfMathFields[mathField.id] = mathField;
MQ(mathFieldSpan).id in setOfMathFields // => true
staticMath.id in setOfMathFields // => false

Data Object¶

Similarly, API objects for the same MathQuill instance share a .data object (which can be used like an ad hoc WeakMap or WeakSet):

MQ(mathFieldSpan).data === mathField.data // => true
mathField.data.foo = 'bar';
MQ(mathFieldSpan).data.foo // => 'bar'

MathQuill base methods¶

The following are methods that every MathQuill object has. These are the only methods that static math instances have and a subset of the methods that editable fields have.

.revert()¶

Any element that has been turned into a MathQuill instance can be reverted:

<span id="revert-me" class="mathquill-static-math">
  some <code>HTML</code>
</span>

mathfield.revert().html(); // => 'some <code>HTML</code>'

.reflow()¶

MathQuill uses computed dimensions, so if they change (because an element was mathquill-ified before it was in the visible HTML DOM, or the font size changed), then you'll need to tell MathQuill to recompute:

var mathFieldSpan = $('<span>\\sqrt{2}</span>');
var mathField = MQ.MathField(mathFieldSpan[0]);
mathFieldSpan.appendTo(document.body);
mathField.reflow();

.el()¶

Returns the root HTML element.

.latex()¶

Returns the contents as LaTeX.

.latex(latex_string)¶

This will render the argument as LaTeX in the MathQuill instance.

Editable MathField methods¶

Editable math fields have all of the above methods in addition to the ones listed here.

.focus()¶

Puts the focus on the editable field.

.blur()¶

Removes focus from the editable field.

.write(latex_string)¶

Write the given LaTeX at the current cursor position. If the cursor does not have focus, writes to last position the cursor occupied in the editable field.

mathField.write(' - 1'); // writes ' - 1' to mathField at the cursor position

.cmd(latex_string)¶

Enter a LaTeX command at the current cursor position or with the current selection. If the cursor does not have focus, it writes it to last position the cursor occupied in the editable field.

mathField.cmd('\\sqrt'); // writes a square root command at the cursor position

.select()¶

Selects the contents (just like on textareas and on inputs).

.clearSelection()¶

Clears the selection.

.moveToLeftEnd(), .moveToRightEnd()¶

Move the cursor to the left/right end of the editable field, respectively. These are shorthand for .moveToDirEnd(L/R), respectively.

.moveToDirEnd(direction)¶

Moves the cursor to the end of the mathfield in the direction specified. The direction can be one of MQ.L or MQ.R. These are constants, where MQ.L === -MQ.R and vice versa. This function may be easier to use than moveToLeftEnd or moveToRightEnd if used in the moveOutOf handler.

var config = {
  handlers: {
    moveOutOf: function(direction) {
      nextMathFieldOver.movetoDirEnd(-direction);
    }
  }
});

.keystroke(keys)¶

Simulates keystrokes given a string like "Ctrl-Home Del", a whitespace-delimited list of key inputs with optional prefixes.

mathField.keystroke('Shift-Left'); // Selects character before the current cursor position

.typedText(text)¶

Simulates typing text, one character at a time from where the cursor currently is. This is supposed to be identical to what would happen if a user were typing the text in.

// Types part of the demo from mathquill.com without delays between keystrokes
mathField.typedText('x=-b\\pm \\sqrt b^2 -4ac');

.config(new_config)¶

Changes the configuration of just this math field.

.dropEmbedded(pageX, pageY, options) ᴇxᴘᴇʀɪᴍᴇɴᴛᴀʟ¶

Insert a custom embedded element at the given coordinates, where options is an object like:

{
  htmlString: '<span class="custom-embed"></span>',
  text: function() { return 'custom_embed'; },
  latex: function() { return '\\customEmbed'; }
}

.registerEmbed('name', function(id){ return options; }) ᴇxᴘᴇʀɪᴍᴇɴᴛᴀʟ¶

Allows MathQuill to parse custom embedded objects from latex, where options is an object like the one defined above in .dropEmbedded(). This will parse the following latex into the embedded object you defined: \embed{name}[id]}.

Note on Experimental Features¶

Methods marked as experimental may be altered drastically or removed in future versions. They may also receive less maintenance than other non-experimental features.