0
# Accessibility
1

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

4
## Import
5

6
```typescript
7
import renderA11yString from "katex/contrib/render-a11y-string";
8
```
9

10
For CommonJS:
11

12
```javascript
13
const renderA11yString = require("katex/contrib/render-a11y-string");
14
```
15

16
## Capabilities
17

18
### Generate Accessibility String
19

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

22
```typescript { .api }
23
/**
24
 * Generates accessibility string for TeX expression  
25
 * @param tex - TeX expression to convert
26
 * @param settings - Optional KaTeX settings
27
 * @returns Human-readable description of the math expression
28
 */
29
function renderA11yString(tex: string, settings?: KatexOptions): string;
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import renderA11yString from "katex/contrib/render-a11y-string";
36

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

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

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

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

50
// With settings
51
renderA11yString("\\color{red}{x}", {
52
  trust: true
53
});
54
// Returns: "start color red, x, end color red"
55
```
56

57
### Supported Mathematical Constructs
58

59
The accessibility string generator handles:
60

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

66
**Advanced Math:**
67
- Powers: `x^2`, `x^3` → "x squared", "x cubed"
68
- Roots: `\sqrt{x}` → "square root of x", `\sqrt[3]{x}` → "cube root of x"
69
- Integrals: `\int` → "integral"
70
- Summations: `\sum` → "sum"
71
- Limits: `\lim` → "limit"
72

73
**Structure:**
74
- Subscripts/Superscripts: Clearly delineated with "start/end subscript/superscript"
75
- Grouping: Parentheses, brackets, braces with appropriate descriptions
76
- Matrices: Described as structured data
77

78
**Usage Example in Web Application:**
79

80
```typescript
81
import katex from "katex";
82
import renderA11yString from "katex/contrib/render-a11y-string";
83

84
function renderMathWithA11y(tex: string, element: HTMLElement) {
85
  // Render visual math
86
  katex.render(tex, element);
87
  
88
  // Add accessibility description
89
  const a11yText = renderA11yString(tex);
90
  element.setAttribute("aria-label", a11yText);
91
  element.setAttribute("role", "img");
92
}
93

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

99
### Integration with Auto-Render
100

101
Enhance auto-rendered content with accessibility:
102

103
```typescript
104
import renderMathInElement from "katex/contrib/auto-render";
105
import renderA11yString from "katex/contrib/render-a11y-string";
106

107
function enhanceWithAccessibility(container: Element) {
108
  // First, auto-render the math
109
  renderMathInElement(container);
110
  
111
  // Then add accessibility attributes to rendered math
112
  const mathElements = container.querySelectorAll('.katex');
113
  mathElements.forEach((element) => {
114
    // Extract original TeX from annotation if available
115
    const annotation = element.querySelector('annotation[encoding="application/x-tex"]');
116
    if (annotation) {
117
      const tex = annotation.textContent;
118
      const a11yText = renderA11yString(tex);
119
      element.setAttribute("aria-label", a11yText);
120
      element.setAttribute("role", "img");
121
    }
122
  });
123
}
124
```
125

126
### Screen Reader Considerations
127

128
The accessibility strings are designed for:
129

130
- **NVDA**: Comprehensive support for mathematical expressions
131
- **JAWS**: Proper reading of mathematical notation  
132
- **VoiceOver**: Clear description of math structures
133
- **Other Screen Readers**: Fallback text descriptions
134

135
**Best Practices:**
136

137
```typescript
138
import katex from "katex";
139
import renderA11yString from "katex/contrib/render-a11y-string";
140

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

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

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

161
### Limitations
162

163
Current limitations of the accessibility string generator:
164

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

170
**Handling Edge Cases:**
171

172
```typescript
173
import renderA11yString from "katex/contrib/render-a11y-string";
174

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