![\"slackin.mathquill.com\"](\"http://slackin.mathquill.com/badge.svg\"){kind=icon}
](http://slackin.mathquill.com)\n[![\"freenode](\"https://img.shields.io/badge/%20freenode%20irc%20-%20%23mathquill%20-brightgreen.svg\"){kind=icon}
](http://webchat.freenode.net/?channels=mathquill)\n\n## Usage\n\nJust load MathQuill and call our constructors on some HTML element DOM objects,\nfor example:\n\n```html\n\n\n\n\n\n Solve ax^2 + bx + c = 0:\n x=\n
\n\n\n```\n\nTo load MathQuill,\n- [jQuery 1.4.3+](http://jquery.com) has to be loaded before `mathquill.js`\n ([Google CDN-hosted copy][] recommended)\n- the fonts should be served from the `font/` directory relative to\n `mathquill.css` (unless you'd rather change where your copy of `mathquill.css`\n includes them from), which is already the case if you just:\n- download and serve [the latest release][].\n\n[Google CDN-hosted copy]: http://code.google.com/apis/libraries/devguide.html#jquery\n[the latest release]: https://github.com/mathquill/mathquill/releases/latest\n\nTo use the MathQuill API, first get the latest version of the interface:\n\n```js\nvar MQ = MathQuill.getInterface(2);\n```\n\nNow you can call `MQ.StaticMath()` or `MQ.MathField()`, which MathQuill-ify\nan HTML element and return an API object. If the element had already been\nMathQuill-ified into the same kind, return that kind of API object (if\ndifferent kind or not an HTML element, `null`). Note that it always returns\neither an instance of itself, or `null`.\n\n```js\nvar staticMath = MQ.StaticMath(staticMathSpan);\nmathField instanceof MQ.StaticMath // => true\nmathField instanceof MQ // => true\nmathField instanceof MathQuill // => true\n\nvar mathField = MQ.MathField(mathFieldSpan);\nmathField instanceof MQ.MathField // => true\nmathField instanceof MQ.EditableField // => true\nmathField instanceof MQ // => true\nmathField instanceof MathQuill // => true\n```\n\n`MQ` itself is a function that takes an HTML element and, if it's the root\nHTML element of a static math or math field, returns an API object for it\n(if not, `null`):\n\n```js\nMQ(mathFieldSpan) instanceof MQ.MathField // => true\nMQ(otherSpan) // => null\n```\n\nAPI objects for the same MathQuill instance have the same `.id`, which will\nalways be a unique truthy primitive value that can be used as an object key\n(like an ad hoc [`Map`][] or [`Set`][]):\n\n```js\nMQ(mathFieldSpan).id === mathField.id // => true\n\nvar setOfMathFields = {};\nsetOfMathFields[mathField.id] = mathField;\nMQ(mathFieldSpan).id in setOfMathFields // => true\nstaticMath.id in setOfMathFields // => false\n```\n\n[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map\n[`Set`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set\n\nSimilarly, API objects for the same MathQuill instance share a `.data` object\n(which can be used like an ad hoc [`WeakMap`][] or [`WeakSet`][]):\n\n```js\nMQ(mathFieldSpan).data === mathField.data // => true\nmathField.data.foo = 'bar';\nMQ(mathFieldSpan).data.foo // => 'bar'\n```\n\n[`WeakMap`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap\n[`WeakSet`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet\n\nAny element that has been MathQuill-ified can be reverted:\n\n```html\n\n someHTML\n\n```\n```js\nMQ($('#revert-me')[0]).revert().html(); // => 'some HTML'\n```\n\nMathQuill uses computed dimensions, so if they change (because an element was\nmathquill-ified before it was in the visible HTML DOM, or the font size\nchanged), then you'll need to tell MathQuill to recompute:\n\n```js\nvar mathFieldSpan = $('\\\\sqrt{2}');\nvar mathField = MQ.MathField(mathFieldSpan[0]);\nmathFieldSpan.appendTo(document.body);\nmathField.reflow();\n```\n\nMathQuill API objects further expose the following public methods:\n\n* `.el()` returns the root HTML element\n* `.html()` returns the contents as static HTML\n* `.latex()` returns the contents as LaTeX\n* `.latex('a_n x^n')` will render the argument as LaTeX\n\nAdditionally, descendants of `MQ.EditableField` (currently only `MQ.MathField`)\nexpose:\n\n* `.focus()`, `.blur()` focuses or defocuses the editable field\n* `.write(' - 1')` will write some LaTeX at the current cursor position\n* `.cmd('\\\\sqrt')` will enter a LaTeX command at the current cursor position or\n with the current selection\n* `.select()` selects the contents (just like [on `textarea`s][] and [on\n `input`s][])\n* `.clearSelection()` clears the current selection\n* `.moveTo{Left,Right,Dir}End()` move the cursor to the left/right end of the\n editable field, respectively. (The first two are implemented in terms of\n `.moveToDirEnd(dir)` where `dir` is one of `MQ.L` or `MQ.R`, constants that\n obey the contract that `MQ.L === -MQ.R` and vice versa.)\n* `.keystroke(keys)` simulates keystrokes given a string like `\"Ctrl-Home Del\"`,\n a whitespace-delimited list of [key values][] with optional prefixes\n* `.typedText(text)` simulates typing text, one character at a time\n* `ᴇxᴘᴇʀɪᴍᴇɴᴛᴀʟ` `.dropEmbedded(pageX, pageY, options)` insert a custom\n embedded element at the given coordinates, where `options` is an object like:\n\n ```js\n {\n htmlString: '',\n text: function() { return 'custom_embed'; },\n latex: function() { return '\\customEmbed'; }\n }\n ```\n* `ᴇxᴘᴇʀɪᴍᴇɴᴛᴀʟ` `.registerEmbed('name', function(id){return options})` 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]}`\n\n[on `textarea`s]: http://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-48880622\n[on `input`s]: http://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-34677168\n[key values]: http://www.w3.org/TR/2012/WD-DOM-Level-3-Events-20120614/#fixed-virtual-key-codes\n\nMathQuill overwrites the global `MathQuill` variable when loaded. You can undo\nthat with `.noConflict()` (similar to [`jQuery.noConflict()`]\n(http://api.jquery.com/jQuery.noConflict)):\n\n```html\n\n\n\n```\n\n(Warning: This lets different copies of MathQuill each power their own\n math fields, but using different copies on the same DOM element won't\n work. Anyway, .noConflict() is primarily to help you reduce globals.)\n\n#### Configuration Options\n\n`MQ.MathField()` can also take an options object:\n\n```js\nvar el = $('x^2').appendTo('body');\nvar mathField = MQ.MathField(el[0], {\n spaceBehavesLikeTab: true,\n leftRightIntoCmdGoes: 'up',\n restrictMismatchedBrackets: true,\n sumStartsWithNEquals: true,\n supSubsRequireOperand: true,\n charsThatBreakOutOfSupSub: '+-=<>',\n autoSubscriptNumerals: true,\n autoCommands: 'pi theta sqrt sum',\n autoOperatorNames: 'sin cos etc',\n substituteTextarea: function() {\n return document.createElement('textarea');\n },\n handlers: {\n edit: function(mathField) { ... },\n upOutOf: function(mathField) { ... },\n moveOutOf: function(dir, mathField) { if (dir === MQ.L) ... else ... }\n }\n});\n```\n\nTo change `mathField`'s options, the `.config({ ... })` method takes an options\nobject in the same format.\n\nGlobal defaults for a page may be set with `MQ.config({ ... })`.\n\nIf `spaceBehavesLikeTab` is true the keystrokes {Shift-,}Spacebar will behave\nlike {Shift-,}Tab escaping from the current block (as opposed to the default\nbehavior of inserting a Space character).\n\nBy default, the Left and Right keys move the cursor through all possible cursor\npositions in a particular order: right into a fraction puts the cursor at the\nleft end of the numerator, right out of the numerator puts the cursor at the\nleft end of the denominator, right out of the denominator puts the cursor to the\nright of the fraction; symmetrically, left into a fraction puts the cursor at\nthe right end of the denominator, etc. Note that right out of the numerator to\nthe left end of the denominator is actually leftwards (and downwards, it's\nbasically wrapped). If instead you want right to always go right, and left to\nalways go left, you can set `leftRightIntoCmdGoes` to `'up'` or `'down'` so that\nleft and right go up or down (respectively) into commands, e.g. `'up'` means\nthat left into a fraction goes up into the numerator, skipping the denominator;\nsymmetrically, right out of the numerator skips the denominator and puts the\ncursor to the right of the fraction, which unlike the default behavior is\nactually rightwards (the drawback is the denominator is always skipped, you\ncan't get to it with just Left and Right, you have to press Down); which is\nthe same behavior as the Desmos calculator. `'down'` instead means it is the\nnumerator that is always skipped, which is the same behavior as the Mac OS X\nbuilt-in app Grapher.\n\nIf `restrictMismatchedBrackets` is true then you can type [a,b) and [a,b), but\nif you try typing `[x}` or `\\langle x|`, you'll get `[{x}]` or\n`\\langle|x|\\rangle` instead. This lets you type `(|x|+1)` normally; otherwise,\nyou'd get `\\left( \\right| x \\left| + 1 \\right)`.\n\nIf `sumStartsWithNEquals` is true then when you type `\\sum`, `\\prod`, or\n`\\coprod`, the lower limit starts out with `n=`, e.g. you get the LaTeX\n`\\sum_{n=}^{ }`, rather than empty by default.\n\n`supSubsRequireOperand` disables typing of superscripts and subscripts when\nthere's nothing to the left of the cursor to be exponentiated or subscripted.\nAverts the especially confusing typo `x^^2`, which looks much like `x^2`.\n\n`charsThatBreakOutOfSupSub` sets the chars that when typed, \"break out\" of\nsuperscripts and subscripts: for example, typing `x^2n+y` normally results in\nthe LaTeX `x^{2n+y}`, you have to hit Down or Tab (or Space if\n`spaceBehavesLikeTab` is true) to move the cursor out of the exponent and get\nthe LaTeX `x^{2n}+y`; this option makes `+` \"break out\" of the exponent and\ntype what you expect. Problem is, now you can't just type `x^n+m` to get the\nLaTeX `x^{n+m}`, you have to type `x^(n+m` and delete the paren or something.\n(Doesn't apply to the first character in a superscript or subscript, so typing\n`x^-6` still results in `x^{-6}`.)\n\n`autoCommands`, a space-delimited list of LaTeX control words (no backslash,\nletters only, min length 2), defines the (default empty) set of \"auto-commands\",\ncommands automatically rendered by just typing the letters without typing a\nbackslash first.\n\n`autoOperatorNames`, a list of the same form (space-delimited letters-only each\nlength>=2), and overrides the set of operator names that automatically become\nnon-italicized when typing the letters without typing a backslash first, like\n`sin`, `log`, etc. Defaults to the LaTeX built-in operator names ([Section\n3.17 of the Short Math Guide][3.17]) plus some missing trig operators like\n`sech`, `arcsec`, `arsinh`, etc.\n\n[3.17]: http://tinyurl.com/jm9okjc\n\n`substituteTextarea`, a function that creates a focusable DOM element, called\nwhen setting up a math field. It defaults to ``,\nbut for example, Desmos substitutes `` on iOS to\nsuppress the built-in virtual keyboard in favor of a custom math keypad that\ncalls the MathQuill API. Unfortunately there's no universal [check for a virtual\nkeyboard][StackOverflow], you can't even [detect a touchscreen][stucox] (notably\n[Modernizr gave up][Modernizr]) and even if you could, Windows 8 and ChromeOS\ndevices have both physical keyboards and touchscreens and you can connect\nphysical keyboards to iOS and Android devices with Bluetooth, so touchscreen !=\nvirtual keyboard. Desmos currently sniffs the user agent for iOS, so Bluetooth\nkeyboards just don't work in Desmos on iOS, the tradeoffs are up to you.\n\n[StackOverflow]: http://stackoverflow.com/q/2593139/362030\n[stucox]: http://www.stucox.com/blog/you-cant-detect-a-touchscreen/\n[Modernizr]: https://github.com/Modernizr/Modernizr/issues/548\n\nSupported handlers:\n- `moveOutOf`, `deleteOutOf`, and `selectOutOf` are called with `dir` and the\n math field API object as arguments\n- `upOutOf`, `downOutOf`, `enter`, and `edit` are called with just the API\n object as the argument\n\nThe `*OutOf` handlers are called when Left/Right/Up/Down/Backspace/Del/\nShift-Left/Shift-Right is pressed but the cursor is at the left/right/top/bottom\nedge and so nothing happens within the math field. For example, when the cursor\nis at the left edge, pressing the Left key causes the `moveOutOf` handler (if\nprovided) to be called with `MQ.L` and the math field API object as arguments,\nand Backspace causes `deleteOutOf` (if provided) to be called with `MQ.L` and\nthe API object as arguments, etc.\n\nThe `enter` handler is called whenever Enter is pressed.\n\nThe `edit` handler is called when the contents of the field might have been\nchanged by stuff being typed, or deleted, or written with the API, etc.\n(Deprecated aliases: `edited`, `reflow`.)\n\nHandlers are always called directly on the `handlers` object passed in,\npreserving the `this` value, so you can do stuff like:\n```js\nvar MathList = P(function(_) {\n _.init = function() {\n this.maths = [];\n this.el = ...\n };\n _.add = function() {\n var math = MQ.MathField($('')[0], { handlers: this });\n $(math.el()).appendTo(this.el);\n math.data.i = this.maths.length;\n this.maths.push(math);\n };\n _.moveOutOf = function(dir, math) {\n var adjacentI = (dir === MQ.L ? math.data.i - 1 : math.data.i + 1);\n var adjacentMath = this.maths[adjacentI];\n if (adjacentMath) adjacentMath.focus().moveToDirEnd(-dir);\n };\n ...\n});\n```\nOf course you can always ignore the last argument, like when the handlers close\nover the math field:\n```js\nvar latex = '';\nvar mathField = MQ.MathField($('#mathfield')[0], {\n handlers: {\n edit: function() { latex = mathField.latex(); },\n enter: function() { submitLatex(latex); }\n }\n});\n```\n\n**A Note On Changing Colors:**\n\nTo change the foreground color, don't just set the `color`, also set\nthe `border-color`, because the cursor, fraction bar, and square root\noverline are all borders, not text. (Example below.)\n\nDue to technical limitations of IE8, if you support it, and want to give\na MathQuill editable a background color other than white, and support\nsquare roots, parentheses, square brackets, or curly braces, you will\nneed to, in addition to of course setting the background color on the\neditable itself, set it on elements with class `mq-matrixed`, and then set\na Chroma filter on elements with class `mq-matrixed-container`.\n\nFor example, to style as white-on-black instead of black-on-white:\n\n #my-math-input {\n color: white;\n border-color: white;\n background: black;\n }\n #my-math-input .mq-matrixed {\n background: black;\n }\n #my-math-input .mq-matrixed-container {\n filter: progid:DXImageTransform.Microsoft.Chroma(color='black');\n }\n\n(This is because almost all math rendered by MathQuill has a transparent\nbackground, so for them it's sufficient to set the background color on\nthe editable itself. The exception is, IE8 doesn't support CSS\ntransforms, so MathQuill uses a matrix filter to stretch parens etc,\nwhich [anti-aliases wrongly without an opaque background][Transforms],\nso MathQuill defaults to white.)\n\n[Transforms]: http://github.com/mathquill/mathquill/wiki/Transforms\n\n## Building and Testing\n\nTo hack on MathQuill, you're gonna want to build and test the source files\nyou edit. In addition to `make`, MathQuill uses some build tools written on\n[Node](http://nodejs.org/#download), so you will need to install that before\nrunning `make`. (Once it's installed, `make` automatically does `npm install`,\ninstalling the necessary build tools.)\n\n- `make` builds `build/mathquill.{css,js,min.js}`\n- `make dev` won't try to minify MathQuill (which can be annoyingly slow)\n- `make test` builds `mathquill.test.js` (used by `test/unit.html`) and also\n doesn't minify\n- `make basic` builds `mathquill-basic.{js,min.js,css}` and\n `font/Symbola-basic.{eot,ttf}`; serve and load them instead for a stripped-\n down version of MathQuill for basic mathematics, without advanced LaTeX\n commands. Specifically, it doesn't let you type LaTeX backslash commands\n with `\\` or text blocks with `$`, and also won't render any LaTeX commands\n that can't by typed without `\\`. The resulting JS is only somewhat smaller,\n but the font is like 100x smaller. (TODO: reduce full MathQuill's font size.)\n\n## Understanding The Source Code\n\nAll the CSS is in `src/css`. Most of it's pretty straightforward, the choice of\nfont isn't settled, and fractions are somewhat arcane, see the Wiki pages\n[\"Fonts\"](http://github.com/mathquill/mathquill/wiki/Fonts) and\n[\"Fractions\"](http://github.com/mathquill/mathquill/wiki/Fractions).\n\nAll the JavaScript that you actually want to read is in `src/`, `build/` is\ncreated by `make` to contain the same JS cat'ed and minified.\n\nThere's a lot of JavaScript but the big picture isn't too complicated, there's 2\nthin layers sandwiching 2 broad but modularized layers:\n\n- At the highest level, the public API is a thin wrapper around calls to:\n- \"services\" on the \"controller\", which sets event listeners that call:\n- methods on \"commands\" in the \"edit tree\", which call:\n- tree- and cursor-manipulation methods, at the lowest level, to move the\n cursor or edit the tree or whatever.\n\nMore specifically:\n\n(In comments and internal documentation, `::` means `.prototype.`.)\n\n- At the lowest level, the **edit tree** of JS objects represents math and text\n analogously to how [the HTML DOM][] represents a web page.\n + (Old docs variously called this the \"math tree\", the \"fake DOM\", or some\n combination thereof, like the \"math DOM\".)\n + `tree.js` defines base classes of objects relating to the tree.\n + `cursor.js` defines objects representing the cursor and a selection of\n math or text, with associated HTML elements.\n- Interlude: a **feature** is a unit of publicly exposed functionality, either\n by the API or interacted with by typists. Following are the 2 disjoint\n categories of features.\n- A **command** is a thing you can type and edit like a fraction, square root,\n or \"for all\" symbol, ∀. They are implemented as a class of node objects\n in the edit tree, like `Fraction`, `SquareRoot`, or `VanillaSymbol`.\n + Each command has an associated **control sequence** (as termed by Knuth;\n in the LaTeX community, commonly called a \"macro\" or \"command\"), a token\n in TeX and LaTeX syntax consisting of a backslash then any single\n character or string of letters, like `\\frac` or \\ . Unlike\n loose usage in the LaTeX community, where `\\ne` and `\\neq` (which print\n the same symbol, ≠) might or might not be considered the same command,\n in the context of MathQuill they are considered different \"control\n sequences\" for the same \"command\".\n- A **service** is a feature that applies to all or many commands, like typing,\n moving the cursor around, LaTeX exporting, LaTeX parsing. Note that each of\n these varies by command (the cursor goes in a different place when moving into\n a fraction vs into a square root, they export different LaTeX, etc), cue\n polymorphism: services define methods on the controller that call methods on\n nodes in the edit tree with certain contracts, such as a controller method\n called on initialization to set listeners for keyboard events, that when the\n Left key is pressed, calls `.moveTowards` on the node just left of the cursor,\n dispatching on what kind of command the node is (`Fraction::moveTowards` and\n `SquareRoot::moveTowards` can insert the cursor in different places).\n + `controller.js` defines the base class for the **controller**, which each\n math field or static math instance has one of, and to which each service\n adds methods.\n- `publicapi.js` defines the global `MathQuill.getInterface()` function, the\n `MQ.MathField()` etc. constructors, and the API objects returned by\n them. The constructors, and the API methods on the objects they return, call\n appropriate controller methods to initialize and manipulate math field and\n static math instances.\n\n[the HTML DOM]: http://www.w3.org/TR/html5-author/introduction.html#a-quick-introduction-to-html\n\nMisc.:\n\n`intro.js` defines some simple sugar for the idiomatic JS classes used\nthroughout MathQuill, plus some globals and opening boilerplate.\n\nClasses are defined using [Pjs][], and the variable `_` is used by convention as\nthe prototype.\n\n[pjs]: https://github.com/jneen/pjs\n\n`services/*.util.js` files are unimportant to the overall architecture, you can\nignore them until you have to deal with code that is using them.\n\n## Open-Source License\n\nThe Source Code Form of MathQuill is subject to the terms of the Mozilla Public\nLicense, v. 2.0: http://mozilla.org/MPL/2.0/\n\nThe quick-and-dirty is you can do whatever if modifications to MathQuill are in\npublic GitHub forks. (Other ways to publicize modifications are also fine, as\nare private use modifications. See also: [MPL 2.0 FAQ][])\n\n[MPL 2.0 FAQ]: https://www.mozilla.org/en-US/MPL/2.0/FAQ/\n\n## umeditor note\n\nmathquill npm version 0.9.1 is from commit 38e162b\n","_attachments":{},"homepage":"https://github.com/mathquill/mathquill#readme","bugs":{"url":"https://github.com/mathquill/mathquill/issues"},"license":"MPL-2.0"}