tessl/npm-katex

Fast math typesetting for the web.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Accessibility

Name: tessl/npm-katex
Author: tessl

Screen reader support and accessibility string generation for math expressions, providing comprehensive text descriptions of mathematical notation.

Import

import renderA11yString from "katex/contrib/render-a11y-string";

For CommonJS:

const renderA11yString = require("katex/contrib/render-a11y-string");

Capabilities

Generate Accessibility String

Converts TeX expressions to human-readable text descriptions for screen readers.

/**
 * Generates accessibility string for TeX expression  
 * @param tex - TeX expression to convert
 * @param settings - Optional KaTeX settings
 * @returns Human-readable description of the math expression
 */
function renderA11yString(tex: string, settings?: KatexOptions): string;

Usage Examples:

import renderA11yString from "katex/contrib/render-a11y-string";

// Basic expressions
renderA11yString("\\frac{1}{2}");
// Returns: "start fraction, 1, divided by, 2, end fraction"

renderA11yString("f(x) = x^2");  
// Returns: "f, left parenthesis, x, right parenthesis, equals, x, squared"

renderA11yString("\\sqrt{x}");
// Returns: "square root of, x, end square root"

renderA11yString("\\int_0^\\infty e^{-x^2} dx");
// Returns: "integral, start subscript, 0, end subscript, start superscript, infinity, end superscript, e, start superscript, negative, x, squared, end superscript, d, x"

// With settings
renderA11yString("\\color{red}{x}", {
  trust: true
});
// Returns: "start color red, x, end color red"

Supported Mathematical Constructs

The accessibility string generator handles:

Basic Operations:

Arithmetic: +, -, *, / → "plus", "minus", "times", "divided by"
Relations: =, <, >, \leq, \geq → "equals", "is less than", etc.
Fractions: \frac{a}{b} → "start fraction, a, divided by, b, end fraction"

Advanced Math:

Powers: x^2, x^3 → "x squared", "x cubed"
Roots: \sqrt{x} → "square root of x", \sqrt[3]{x} → "cube root of x"
Integrals: \int → "integral"
Summations: \sum → "sum"
Limits: \lim → "limit"

Structure:

Subscripts/Superscripts: Clearly delineated with "start/end subscript/superscript"
Grouping: Parentheses, brackets, braces with appropriate descriptions
Matrices: Described as structured data

Usage Example in Web Application:

import katex from "katex";
import renderA11yString from "katex/contrib/render-a11y-string";

function renderMathWithA11y(tex: string, element: HTMLElement) {
  // Render visual math
  katex.render(tex, element);
  
  // Add accessibility description
  const a11yText = renderA11yString(tex);
  element.setAttribute("aria-label", a11yText);
  element.setAttribute("role", "img");
}

// Usage
const mathElement = document.getElementById("equation");
renderMathWithA11y("\\frac{d}{dx}[x^2] = 2x", mathElement);

Integration with Auto-Render

Enhance auto-rendered content with accessibility:

import renderMathInElement from "katex/contrib/auto-render";
import renderA11yString from "katex/contrib/render-a11y-string";

function enhanceWithAccessibility(container: Element) {
  // First, auto-render the math
  renderMathInElement(container);
  
  // Then add accessibility attributes to rendered math
  const mathElements = container.querySelectorAll('.katex');
  mathElements.forEach((element) => {
    // Extract original TeX from annotation if available
    const annotation = element.querySelector('annotation[encoding="application/x-tex"]');
    if (annotation) {
      const tex = annotation.textContent;
      const a11yText = renderA11yString(tex);
      element.setAttribute("aria-label", a11yText);
      element.setAttribute("role", "img");
    }
  });
}

Screen Reader Considerations

The accessibility strings are designed for:

NVDA: Comprehensive support for mathematical expressions
JAWS: Proper reading of mathematical notation
VoiceOver: Clear description of math structures
Other Screen Readers: Fallback text descriptions

Best Practices:

import katex from "katex";
import renderA11yString from "katex/contrib/render-a11y-string";

// Always include MathML for better screen reader support
katex.render(tex, element, {
  output: "htmlAndMathml" // Default, includes both HTML and MathML
});

// Add aria-label for additional context
const a11yText = renderA11yString(tex);
element.setAttribute("aria-label", `Math expression: ${a11yText}`);
element.setAttribute("role", "img");

// For complex expressions, consider adding aria-describedby
const descriptionId = "math-desc-" + Math.random().toString(36).substr(2, 9);
const description = document.createElement("div");
description.id = descriptionId;
description.className = "sr-only"; // Visually hidden
description.textContent = a11yText;
document.body.appendChild(description);
element.setAttribute("aria-describedby", descriptionId);

Limitations

Current limitations of the accessibility string generator:

Complex Expressions: Very complex expressions may have verbose descriptions
Custom Macros: Custom macros may not have semantic descriptions
Visual Layout: Spatial relationships (like matrices) are described structurally, not visually
Language: Descriptions are currently in English only

Handling Edge Cases:

import renderA11yString from "katex/contrib/render-a11y-string";

try {
  const a11yText = renderA11yString(tex);
  element.setAttribute("aria-label", a11yText);
} catch (error) {
  // Fallback for expressions that can't be converted
  element.setAttribute("aria-label", "Mathematical expression");
  console.warn("Could not generate accessibility text for:", tex);
}