Accessibility Extensions Options

MathJax contains several extensions meant to support those who need assistive technology, such as screen readers. See the Accessibility Components page for more details. The options that control these extensions are listed below.

Semantic-Enrich Extension Options
Speech Extension Options
Complexity Extension Options
Explorer Extension Options
Assisitve-MML Extension Options

Because the accessibility extensions are controlled by the settings of the MathJax contextual menu, when the ui/menu is loaded, you use the Contextual Menu Options to determine whether they are enabled or not. There are settings below that can be used to disable the extensions, in case they are loaded automatically, but these are not the settings that control whether the extensions themselves are loaded. That is controlled by the menu settings:

MathJax = {
  options: {
    menuOptions: {
      settings: {
        enrich: true,         // true to enable semantic-enrichment
        collapsible: false,   // true to enable collapsible math
        speech: true,         // true to enable speech generation
        braille: true,        // true to enable Braille generation
        assistiveMml: false,  // true to enable assistive MathML
      }
    }
  }
};

Note

The explorer option has been removed in v4, and is replaced by the speech and braille options, which determine whether the explorer is active (either one will activate the explorer). The semantic-enrichment is controlled by the new enrich option, and is required for both the complexity computations and the speech and Braille generation; disabling enrichment effectively disables nearly all the accessibility tools at once.

In version 3, the accessibility tools were off and the assistive MathML was on by default, meaning users had to enable to explorer by hand if they wanted to use it. In version 4, the reverse is true: the accessibility extensions are included and enabled in all the combined components, and the assistive MathML is off. This means users will be able to explore expressions immediately without the need to change menu settings.

If you are not using a combined component, you can load the extensions explicitly using the Loader Options, but it is probably better to use the menu options above, so that if a user turns the extensions off, they will not incur the network and startup costs of loading the extensions they will not be using.

Note

In version 4, the MathJax contextual menu has been redesigned to give more prominence to the accessibility tools, and they are now at the top level of the menu rather than hidden in a submenu.

Semantic-Enrich Extension Options

This extension coordinates the creation and embedding of semantic information generated by the enrichment process within the MathJax output for use by the other extensions. The semantic-enrich extension adds an enrich action to the document’s default renderActions object.

The Configuration Block

MathJax = {
  options: {
    enableEnrichment: true,   // false to disable enrichment
    enrichError: (doc, math, err) => doc.enrichError(doc, math, err),  // function to call if enrichment fails
  }
};

Option Descriptions

enableEnrichment: true: This setting controls whether semantic enrichment is applied to the internal MathML representation of the mathematics in the page when the semantic-enrich extension is loaded. This is controlled automatically by the settings of the context menu, so you should use those to control semantic-enrichment if the menu component is present. If not, you can use it to disable semantic enrichment if the semantic-enrich component has been loaded automatically and you don’t need it.

enrichError: (doc, math, err) => doc.enrichError(doc, math, err): This setting provides a function that gets called when the semantic enrichment process fails for some reason. The default is to call the MathDocument’s enrichError() method, which simply prints a warning message in the browser console window. The original (unenriched) MathML will be used for the output of the expression. You can override the default behavior by providing a function that does whatever you want, such as recording the error, or replacing the original MathML with alternative MathML containing an error message.

Note

In version 3, the semantic-enrich extension handled both enrichment and speech generation. These two functions have been separated in version 4, and speech is now processed in the new speech extension described below. The sre block that was listed here in v3 has been moved to the speech extension.

Speech Extension Options

This extension coordinates the generation of speech strings Braille notation that are added to the HTML or SVG nodes within the page where they can be used by screen readers, or by the a11y/explorer. The speech extension adds an attachSpeech action to the document’s default renderActions object.

The Configuration Block

MathJax = {
  options: {
    enableSpeech: true,       // false to disable speech strings
    enableBraille: true,      // false to disable Braille notation
    speechError: (doc, math, err) => doc.speechError(doc, math, err),  // called if speech generation fails
    sre: {
      domain: 'mathspeak',    // speech rules domain
      style: 'default',       // speech rules style
      locale: 'en'            // the language to use (en, fr, es, de, it)
    },
    a11y: {
      speech: true,           // switch on speech output when enabled
      braille: true,          // switch on Braille output when enabled
    },
    worker: {
      path: 'path-to-bundle/a11y/sre',   // full path to bundle/a11y/sre (set automatically)
      maps: 'path-to-sre/lib/mathmaps',  // full path to sre's speech rules
      worker: 'speech-worker.js',        // name of worker script to load as a webworker
      debug: false,                      // true to include debugging messages in the browser console about
                                         //   the communications between the page, worker pool, and workers.
    },
  }
};

Option Descriptions

enableSpeech: true: This setting controls whether speech strings are generated and attached to the DOM elements within the page when the speech extension is loaded. This is controlled automatically by the settings of the context menu, so you should use those to control speech generation if the menu component is present. If not, you can use it to disable speech generation if the speech component has been loaded automatically and you don’t need it.

enableBraille: true: This setting controls whether Braille labels are generated and attached to the DOM elements within the page when the speech extension is loaded. This is controlled automatically by the settings of the context menu, so you should use those to control Braille labels if the menu component is present. If not, you can use it to disable Braille generation if the speech component has been loaded automatically and you don’t need it.

enrichError: (doc, math, err) => doc.enrichError(doc, math, err): This setting provides a function that gets called when the speech or Braille generation fails for some reason. The default is to call the MathDocument’s speechError() method, which simply prints a warning message in the browser console window. You can override the default behavior by providing a function that does whatever you want, such as recording the error.

sre: {...}: This block sets configuration values for the Speech-Rule Engine (SRE) that underlies MathJax’s speech and Braille features. See the SRE documentation for more details.

worker: {...}: This block gives parameters that control the speech generation, which is performed using webworkers so that this time-consuming process will not interfere with the responsiveness of the page. You should not need to change these.

Complexity Extension Options

This extension generates a complexity metric and inserts elements that allow the expressions to be collapsed by the user by clicking on the expression based on that metric. The complexity extension adds a complexity action to the document’s default renderActions object.

The Configuration Block

MathJax = {
  options: {
    enableComplexity: true,       // set to false to disable complexity computations
    makeCollapsible: true         // insert mactions to allow collapsing
  }
};

Option Descriptions

enableComplexity: true: This setting controls whether the complexity extension is to run or not when it is loaded. The value is controlled automatically by the settings of the context menu, so you should use those to control the complexity computations if the menu component is present. If not, you can use it to disable the computations if the complexity component has been loaded automatically and you don’t need it.

makeCollapsible: true: This setting determines whether the extension will insert <maction> elements to allow complex expressions to be “collapsed” so that they take up less space, and produce condensed speech strings that are simpler to listen to. When false, the expression is not altered, but elements are marked (internally) if they would be collapsible.

Developer Options

identifyCollapsible: true: This setting determines whether the complexity numbers computed for each element in the expression should take collapsing into account. If true, parents of collapsible elements will get complexities that reflect the collapsible elements being collapsed. When false, the complexities assume no collapsing will take place.

Collapse: Collapse: The Collapse object class to use for creating the <maction> elements needed for collapsing complex expressions. This allows you to create a subclass of Collapse and pass that to the document.

ComplexityVisitor: ComplexityVisitor: The ComplexityVisitor object class to use for managing the computations of complexity values. This allows you to create a subclass of ComplexityVisitor and pass that to the document.

Explorer Extension Options

This extension provides support for interactive exploration of expressions within the page. See the Accessibility Features page for details about how this works.

The explorer extension adds an explorable action to the document’s default renderActions object.

The Configuration Block

MathJax = {
  options: {
    enableExplorer: true,                // set to false to disable the explorer
    enableExplorerHelp: true,            // set to false to disable the help icon and dialog
    a11y: {
      speech: true,                      // switch on speech output
      braille: true,                     // switch on Braille output
      subtitles: true,                   // show speech as a subtitle
      viewBraille: false,                // display Braille output as subtitles
      help: true,                        // include "press h for help" messages on focus
      roleDescription: 'math',           // the role description to use for math expressions
      voicing: false,                    // switch on speech output

      backgroundColor: 'Blue',           // color for background of selected sub-expression
      backgroundOpacity: .2,             // opacity for background of selected sub-expression
      foregroundColor: 'Black',          // color to use for text of selected sub-expression
      foregroundOpacity: 1,              // opacity for text of selected sub-expression

      highlight: 'None',                 // type of highlighting for collapsible sub-expressions
      flame: false,                      // color collapsible sub-expressions
      hover: false,                      // show collapsible sub-expression on mouse hovering

      treeColoring: false,               // tree color expression

      magnification: 'None',             // type of magnification
      magnify: '400%',                   // percentage of magnification of zoomed expressions
      keyMagnifier: false,               // switch on magnification via key exploration
      mouseMagnifier: false,             // switch on magnification via mouse hovering
      align: 'top',                      // placement of magnified expression

      infoType: false,                   // show semantic type on mouse hovering
      infoRole: false,                   // show semantic role on mouse hovering
      infoPrefix: false,                 // show speech prefixes on mouse hovering
    }
  }
};

Option Descriptions

enableExplorer: true: This setting controls whether the explorer extension is to run or not when it is loaded. The value is controlled automatically by the settings of the context menu, so you should use those to control whether expressions are explorable if the menu component is present. If not, you can use it to disable the explorer if the explorer component has been loaded automatically and you don’t need it.

enableExplorerHelp: true: This controls whether the small “info” icon is displayed at the upper right-hand corner of an expression when it is focused. Setting it to false will prevent the icon from appearing, will disable the “press H for help” message from being spoken when an expression is first focused, and disables the help dialog when the “h” key is pressed during expression exploration. This means that users of assistive technology will be unable to obtain help on how to use MathJax’s assistive features, so you should not set this to false if your pages may be viewed by users with accessibility needs.

The a11y options are all controlled by the MathJax contextual menu, when the menu component is present, so you should use the corresponding menu options to set these values in that case. If the menu component is not loaded, you can use the options below to control the explorer directly.

The options belong roughly to one of the following four categories:

Speech Options

speech: true: Determines whether speech output is produced. By default, speech is computed for every expression on the page, and will be voiced by a screen reader when the page is read, or when the explorer is started.

braille: true: Determines whether Braille output is produced. By default, Braille is computed for every expression on the page, and will be sent to a Braille output device when the page is read, or when the explorer is started.

subtitles: true: This option specifies whether the speech string for the selected sub-expression will be shown as a subtitle under the expression as it is explored.

viewBraille: false: This option specifies whether Braille output will be displayed under the expression as it is explored.

help: true: This option specifies whether the explorer should voice “press h for help” when an expression becomes focused. This helps new users to realize that help is available, but experienced users may wish to disable this feature.

roleDescription: 'math': This option specifies what description should be voiced by screen readers when reading a MathJax expression; for example, the expression E = mc^2 might be read as “E equals m c squared, math”. The value to use can be set using the MathJax contextual menu to one of several options, including no description.

voicing: true: This option determines whether MathJax will read expressions using the Browser’s voice API during expression exploration. That can be useful for people who are not using a screen reader, but still want to hear the spoken expression.

Note

As of version 3.1.3, the speechRules option has been broken into two separate options, domain and style, in the sre block of the configuration. See the Speech Extension Options above for more.

Highlighting Options

foregroundColor: 'Black': This specifies the color to use for the text of the selected sub-expression during expression exploration. The color should be chosen from among the following: 'Blue', 'Red', 'Green', 'Yellow', 'Cyan', 'Magenta', 'White', and 'Black'.

foregroundOpacity: 1: This indicates the opacity to use for the text of the selected sub-expression, with 1 begin fully opaque, and 0 being totally transparent.

backgroundColor: 'Blue': This specifies the background color to use for the selected sub-expression during expression exploration. The color should be chosen from among the following: 'Blue', 'Red', 'Green', 'Yellow', 'Cyan', 'Magenta', 'White', and 'Black'.

backgroundOpacity: .2: This indicates the opacity to use for the background color of the selected sub-expression, with 1 begin fully opaque, and 0 being totally transparent.

highlight: 'None': Chooses a particular highlighter for showing collapsible sub-expressions. Choices are 'None', 'Flame', and 'Hover'.

flame: false: This flag switches on the Flame highlighter, which permanently highlights collapsible sub-expressions, with successively darkening background for nested collapsible expressions.

hover: false

This switches on the Hover highlighter that highlights collapsible sub-expression when hovering over them with a the mouse pointer.

Note, that having both 'hover' and 'flame' set to true can lead to unexpected side-effects.

treeColoring: false: This setting enables tree coloring, by which expressions are visually distinguished by giving neighbouring symbols different, ideally contrasting foreground colors.

Magnification Options

magnification: 'None': This option specifies a particular magnifier for enlarging sub-expressions. Choices are 'None', 'Keyboard', and 'Mouse'.

magnify: '400%': This gives the magnification factor (as a percent) to use for the zoomed sub-expression when zoomed sub-expressions are being displayed during expression exploration. The default is 400%.

keyMagnifier: false: Switches on zooming of sub-expressions during keyboard exploration of an expression.

mouseMagnifier: false

Switches on zooming of sub-expressions by hovering with the mouse pointer.

Note, using both 'keyMagnifier' and 'mouseMagnifier together can lead to unwanted side-effect.

align: 'top': This setting tells where to place the zoomed version of the selected sub-expression, when zoomed sub-expressions are being displayed during expression exploration.

Semantic Info Options

Semantic information explorers are a feature that displays some semantic information of a sub-expression when hovering over it with the mouse pointer. Note, multiple information explorers work well together.

infoType: false: Activates an explorer that investigates the semantic type of sub-expressions. The type is an immutable property of an expression, that is independent of its particular position in a formula. Note, however that types can change depending on subject area of a document.

infoRole: false: Activates an explorer to present the semantic role of a sub-expression, which is dependent on its context in the overall expression.

infoPrefix: false

Activates explorer for prefix information, which pertains to the position of a sub-expression. Examples are 'exponent', 'radicand', etc. These would also be announced during interactive exploration with speech output.

For more details on these concepts, see also the documentation of the Speech Rule Engine.

Note

While multiple keyboard-based exploration techniques work well together and can be easily employed simultaneously, switching on multiple mouse-based exploration tools can lead to unexpected interactions of the tools and often unpredictable side effects.

Assisitve-MML Extension Options

This extension adds visually hidden MathML to MathJax’s output that can be voiced by some screen readers. See the Screen Reader Support section for more details on how this works. The extension adds an action to the document’s default renderActions object that does the MathML insertion. You can disable that by using the following configuration.

Note

In version 3, the assistive-mml extension was included in all the combined components, and was active by default. That is no longer the case in v4, where the other accessibility tools are included and enabled by default. Users who prefer the assistive MathML can turn off the semantic enrichment (which will disable the other tools), and turn on the assistive MathML using the MathJax contextual menu (in the Options submenu in the Accessibility section of the main menu.

The Configuration Block

MathJax = {
  options: {
    enableAssistiveMml: false
  }
};

Option Descriptions

enableAssistiveMml: false: This setting controls whether the assistive-mml extension is to run or not when it is loaded. The value is controlled automatically by the settings of the context menu, so when the menu component is present, you should use those to control whether assistive MathML is inserted. If the menu is not available, you can use this option to disable the assistive MathML if the assistive-mml component has been loaded automatically and you don’t need it.