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

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 two actions to the document’s default renderActions object: an enrich action to perform the semantic enrichment, and an attachSpeech action to attach speech (if it is being generated) to the output.

The Configuration Block

MathJax = {
  options: {
    enrichSpeech: 'none',    // or 'shallow', or 'deep'
  }
};

Option Descriptions

enrichSpeech: 'none'

This setting controls whether MathJax uses the Speech-Rule Engine (SRE) to generate a speech string for the expressions on the page. If set to 'none' (the default), no speech is generated. When set to 'shallow', speech is generated only for the complete equation, and when set to 'deep', every speakable element is marked with its speech string. These speech strings are put in data-semantic-speech attributes, when generated. The output processors will find the top-most speech string and set the appropriate attributes on the output they generate so that screen readers can find it.

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. Use the 'a11y/complexity' block of your MathJax configuration to configure the extension.

The complexity extension adds a complexity action to the document’s default renderActions object.

The Configuration Block

MathJax = {
  options: {
    makeCollapsible: true         // insert maction to allow collapsing
  }
};

Option Descriptions

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: {
    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
      speechRules: 'mathspeak-default',  // speech rules as domain-style pair

      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

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

Speech Options

speech: true

Sets if speech output is produced. By default speech is computed for every expression on the page and output once the explorer is started.

braille: true

Sets whether or not Braille is produced and output for an expression.

subtitles: true

This option indicates 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 indicates whether Braille output will be displayed under the expression as it is explored.

speechRules: 'mathspeak-default'

This option selects the speech rules used for speech generation in a domain-style pair. For a list of possible selections please see the documentation of the Speech Rule Engine, e.g., by running

npx speech-rule-engine --options

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.

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.

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 highligher, 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 assisitive-mml extension is included in all the combined components, and is active by default, so screen reader users will not need to do anything to activate it. There is a menu item that controls whether to insert the assistive MathML, so visual users can turn it off if they wish.

The extension adds an action to the document’s default renderActions object that does the MathML insertion. You can override that by using the following configuration.

MathJax = {
  options: {
    renderActions: {
      assistiveMML: []
    }
  }
};