fxTeX API

Setup

fxTeX needs none. Its functions can be called as soon as the script has loaded, and every one of them runs synchronously.

fxTeX Pro is WebAssembly, which loads asynchronously, and is opened with your licence key. Wait for ready, then unlock(), before converting anything (autoRender() waits for ready by itself):

<script src="https://fxtex.codecogs.com/fx_pk_your-key-here/fxtexpro.min.js"></script>
<script>
  fxTeXPro.ready.then(() => {
    fxTeXPro.unlock('fx_pk_your-key-here');
    fxTeXPro.autoRender();
  });
</script>Copy

Your key is in the licence manager, alongside a copy of the lines above with it filled in. It is safe to put in a page: it only opens fxTeX Pro on the domain it was issued for. See licence options.

render()

fxTeX.render(options?)
fxTeXPro.render(options?)   // returns a promise

Finds the LaTeX under options.root (the whole page by default) — delimited text such as $x^2$, and equation images — and replaces each with MathML, in place. The options below choose what it looks for and how the equations come out.

fxTeX.render({ root: document.querySelector('main article'), images: false });Copy

It is safe to call as often as you like. Already-converted equations are <math> elements, which the default ignoreSelector excludes, so a second pass never double-converts anything — which makes it the way to render content your own code adds to the page later.

fxTeX's render() is synchronous: the equations are MathML by the line after it. fxTeX Pro's is too, but returns a promise as well, which is already resolved — except the first time format: 'svg' is asked for, when it renders once the SVG module has loaded.

Its relatives

All four take the same options.

Render options

All of them together:

fxTeX.render({
  root: document.getElementById('article'),   // default: document.body
  delimiters: fxTeX.DEFAULT_DELIMITERS,       // $ and $$ only
  ignoreSelector: 'script, style, textarea, pre, code, noscript, math, .no-cc-render',
  text: true,                                 // false skips the delimiter scan entirely
  images: {                                   // false skips the image scan entirely
    imgSelector: 'img[src*="codecogs.com/svg.image"]',
    dataImgSelector: 'img[data-latex-src], img[data-latex]',
    templateSelector: 'template.cc-equation'
  },
  speech: fxTeX.WRAPPER_LABEL,                 // how spoken text is attached (default WRAPPER_LABEL)
  fontSize: '120%',                           // each equation's font size: '120%', '18px'...
  lengths: { arraycolsep: '3pt' },            // TeX's lengths, as a preamble's \setlength
  contextMenu: { server: 'https://fxtex.codecogs.com/' },   // the right-click menu's servers
  onError: function (source, err) { console.warn('Could not render', source, err); }
});Copy

root

The subtree to scan. Narrowing it is the main performance control: a page whose equations all live inside one article element has no reason to walk its navigation, footer and comment thread. It is also how you re-render just the part of a page your own code has changed.

delimiters

An array of { left, right, display }. display: true is a centred block, false is inline. Longer delimiters win ties, so $$ is always read as a block and never as two empty $ pairs. Supplying this option replaces the default set rather than adding to it, so spread DEFAULT_DELIMITERS back in to add to it:

fxTeX.render({
  delimiters: [...fxTeX.DEFAULT_DELIMITERS, ...fxTeX.LATEX_BRACKET_DELIMITERS]
});Copy

ignoreSelector

A CSS selector. Any element matching it is skipped, and so is everything inside it. Replace the default if you need a different exclusion — a documentation site that writes its samples in <samp>, say — and keep math in whatever you replace it with, or a second render() call will try to convert output from the first.

text

Set false on a page whose equations are all images. It skips building the text walker at all, which is cheaper than running one over text that was never going to match.

images

Set false on a page that has no equation images, or pass an object to change which elements count as one:

The overview's Equation images explains the three, and which to use.

speech

How each equation's spoken text is attached for screen readers. On by default as WRAPPER_LABEL; set one of four values:

• fxTeX.WRAPPER_LABEL (1) — the speech becomes the accessible name of a span around the equation, so a reader announces the name instead of descending into the MathML. The default, and the one observed to work most widely.
• fxTeX.HIDDEN_SPAN (2) — the MathML is left for readers that speak it natively, with the text beside it in a visually-hidden span.
• fxTeX.ARIA_LABEL (3) — the text is an aria-label on the <math> element itself.
• fxTeX.OFF (0) — no spoken text; plain MathML, read by whatever native support the browser and screen reader have between them.

convertToMathML() is the one exception to the default: it returns plain MathML with no speech. The accessibility test bench shows what screen readers make of each.

fontSize

The font size of every equation this call renders, as any CSS font size: '120%' of the text around it makes them a fifth larger, and '18px', '1.2em' or 'large' work too. It is set as font-size on each equation's outermost element, so everything inside scales with it — MathML, and fxTeX Pro's SVG alike. A value CSS's font-size does not take is ignored, with a warning in the console, and the page renders at the normal size.

To size every equation on a site instead, set --fxtex-font-size in your own stylesheet. fxTeX's stylesheet sizes each equation from it, and fxTeX Pro's does too. Set it on :root for the whole page, or on any element for the equations inside it:

:root { --fxtex-font-size: 120%; }      /* every equation on the page */
.sidebar { --fxtex-font-size: 90%; }    /* or only those in one part of it */Copy

It takes any CSS font size, as fontSize does. Left unset, equations keep the size of the text around them. A render's own fontSize takes precedence over it, so a page can set a site-wide size and still enlarge one part of it with render({ root, fontSize }).

lengths

Five of TeX's lengths shape the tables, aligned equations and boxes fxTeX draws. In an equation, \setlength changes one from there to the end of that equation; for a whole page, the lengths option sets them for every equation under root, and an equation's own \setlength still wins.

fxTeX.render({ lengths: { arraycolsep: '3pt', fboxsep: '1pt' } });   // the whole page
// or, in one equation: $\setlength{\arraycolsep}{3pt} \begin{pmatrix} a & b \end{pmatrix}$Copy

Each is also a CSS custom property, --fxtex-arraycolsep and so on, which a page's own stylesheet can set. The page-wide setting applies in the browser; fxTeX Server's images use the defaults, or an equation's own \setlength.

contextMenu

The right-click menu's settings: the servers its image and graph items use and, in fxTeX Pro, how much of the menu there is — mode, one of 'full' (the default), 'copy' or 'disable':

fxTeXPro.autoRender({ contextMenu: { mode: 'copy' } });Copy

See the menu's Configuration for the servers. configureContextMenu() takes the same object, at any time.

format

fxTeX Pro only. 'mathml', the default, leaves each equation as MathML for the browser to draw. 'svg' draws it as SVG instead, so it looks the same in every browser — see SVG output.

onError

Called with (source, error) for any equation that fails to parse. Without it a malformed equation is left exactly as it was written and the scan carries on; one bad equation never takes down the rest of the page.

convertToMathML()

fxTeX.convertToMathML(latex, display?)

Converts one LaTeX string and returns its MathML. Nothing is scanned and nothing is inserted; what you do with the string is your business. display is false for an inline equation (the default), true for a block one. The output has no spoken text.

fxTeX.convertToMathML('\\frac{1}{2}');        // inline
fxTeX.convertToMathML('\\frac{1}{2}', true);  // displayCopy

It needs no document, so it also runs under Node — see Rendering server-side. For spoken text, a font size or any other setting, use fxTeX Pro's converter.

converter()

fxTeXPro.converter()

fxTeX Pro only. convertToMathML() takes LaTeX and a display flag and nothing else. For more control — spoken text for screen readers, or a font size — converter() hands you the converter itself, once ready has resolved and the key is unlocked:

fxTeXPro.ready.then(() => {
  fxTeXPro.unlock('fx_pk_your-key-here');
  const c = fxTeXPro.converter();
  c.setSpeech(true, 'verbose');
  const mathml = c.convert('\\frac{a}{b}');
  const spoken = c.getSpeech();   // the spoken text - read it straight after convert()
});Copy

There is one converter per page, and it is the one render() and convertToMathML() use too. Two things follow:

Set every setting your code relies on before converting, rather than assuming the defaults: render() sets the speech settings to its own speech option each time it runs.

Put setInline, setDisplayStyle, setFontSize, setEmitPositions and setCursor back as you found them — false, false, null, false and -1 — before the page renders again. render() does not reset them, so a page left with setInline(true) would set its $$...$$ equations inline, and one left with setFontSize('150%') would draw every equation it renders at that size unless the render passes a fontSize of its own.

The equation editor has its own version of this, EqEditor.newConverter(), which gives each caller a converter with settings of its own.

SVG output

fxTeX Pro only. MathML is drawn by the browser, and browsers draw it a little differently. fxTeX Pro can draw each equation itself instead, as an <svg> that looks the same everywhere — with the same layout engine fxTeX Server makes its images with, and the same spoken text as MathML:

fxTeXPro.ready.then(() => {
  fxTeXPro.unlock('fx_pk_your-key-here');
  fxTeXPro.autoRender({ format: 'svg' });
});Copy

The SVG module and its font are a separate download, fetched from beside fxtexpro.min.js the first time SVG is asked for. render() and autoRender() wait for them; should they not load, the page is rendered as MathML instead and the console says why. Equations are sized in ems, so fontSize and --fxtex-font-size size them as they do MathML.

Packages

fxTeX Pro only. Three optional packages — mhchem, chemfig and physics — are left out unless a page asks for them, so a page that does not use them neither downloads them nor converts their commands. Name them to autoRender(), or to usePackages() before rendering yourself:

fxTeXPro.autoRender({ packages: ['physics', 'chemfig'] });

// or, rendering yourself
await fxTeXPro.ready;
fxTeXPro.unlock('fx_pk_your-key-here');
await fxTeXPro.usePackages(['physics', 'chemfig']);
fxTeXPro.render();Copy

usePackages() fetches each package from beside fxtexpro.min.js and resolves once its commands are ready, so render after it. A name your licence does not offer, or a misspelt one, is reported in the console and skipped. Asking twice is harmless. See Using packages for what each one adds.

Utilities and constants

More

Overview — installing fxTeX, what it finds, and common tasks.

Right-click menu — copying equations, and the graph and calculator.

Supported commands — every LaTeX command fxTeX reads, each with an example.

fxEditor API — the equation editor, for pages where your users write the maths.