0
# Auto-Rendering
1

2
Automatic math detection and rendering within HTML elements, supporting configurable delimiters and preprocessing for seamless integration into web pages.
3

4
## Import
5

6
```typescript
7
import renderMathInElement from "katex/contrib/auto-render";
8
```
9

10
For CommonJS:
11

12
```javascript
13
const renderMathInElement = require("katex/contrib/auto-render");
14
```
15

16
## Capabilities
17

18
### Render Math in Element
19

20
Automatically finds and renders math expressions within an HTML element using configurable delimiters.
21

22
```typescript { .api }
23
/**
24
 * Automatically renders math within an HTML element
25
 * @param element - DOM element to search for math expressions
26
 * @param options - Auto-rendering configuration options
27
 */
28
function renderMathInElement(element: Element, options?: AutoRenderOptions): void;
29

30
interface AutoRenderOptions extends KatexOptions {
31
  /** Math delimiter configurations */
32
  delimiters?: DelimiterConfig[];
33
  /** HTML tags to ignore during processing */
34
  ignoredTags?: string[];
35
  /** CSS classes to ignore during processing */
36
  ignoredClasses?: string[];
37
  /** Error callback function */
38
  errorCallback?: (msg: string, err: Error) => void;
39
  /** Preprocessing function for math strings */
40
  preProcess?: (math: string) => string;
41
}
42

43
interface DelimiterConfig {
44
  /** Opening delimiter */
45
  left: string;
46
  /** Closing delimiter */
47
  right: string;
48
  /** Whether to render in display mode */
49
  display: boolean;
50
}
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
import katex from "katex";
57
import renderMathInElement from "katex/contrib/auto-render";
58

59
// Basic auto-rendering
60
const container = document.getElementById("content");
61
renderMathInElement(container);
62

63
// Custom configuration
64
renderMathInElement(container, {
65
  delimiters: [
66
    { left: "$$", right: "$$", display: true },
67
    { left: "$", right: "$", display: false },
68
    { left: "\\(", right: "\\)", display: false },
69
    { left: "\\[", right: "\\]", display: true }
70
  ],
71
  ignoredTags: ["script", "noscript", "style", "textarea", "pre", "code"],
72
  ignoredClasses: ["no-math", "skip-math"],
73
  throwOnError: false
74
});
75

76
// With preprocessing
77
renderMathInElement(container, {
78
  preProcess: (math) => {
79
    // Replace custom syntax
80
    return math.replace(/\[vec\]/g, "\\vec");
81
  },
82
  errorCallback: (msg, err) => {
83
    console.warn("Math rendering error:", msg, err);
84
  }
85
});
86
```
87

88
### Default Delimiters
89

90
The default delimiter configuration includes:
91

92
```typescript { .api }
93
const defaultDelimiters: DelimiterConfig[] = [
94
  { left: "$$", right: "$$", display: true },
95
  { left: "\\(", right: "\\)", display: false },
96
  { left: "\\[", right: "\\]", display: true },
97
  
98
  // AMS environments
99
  { left: "\\begin{equation}", right: "\\end{equation}", display: true },
100
  { left: "\\begin{align}", right: "\\end{align}", display: true },
101
  { left: "\\begin{alignat}", right: "\\end{alignat}", display: true },
102
  { left: "\\begin{gather}", right: "\\end{gather}", display: true },
103
  { left: "\\begin{CD}", right: "\\end{CD}", display: true }
104
];
105
```
106

107
### Content Processing
108

109
Auto-render processes text nodes and handles:
110

111
- **Delimiter Detection**: Finds math expressions using configured delimiters
112
- **Tag Filtering**: Skips specified HTML tags (default: script, noscript, style, textarea, pre, code, option)
113
- **Class Filtering**: Skips elements with specified CSS classes
114
- **Text Node Concatenation**: Handles large text nodes split by browsers
115
- **Error Handling**: Continues processing on errors with configurable callbacks
116

117
**HTML Example:**
118

119
```html
120
<div id="content">
121
  <p>The quadratic formula is \\(x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}\\).</p>
122
  <p>Display math: $$\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}$$</p>
123
  <code class="no-math">\\(this will be ignored\\)</code>
124
</div>
125

126
<script>
127
import renderMathInElement from "katex/contrib/auto-render";
128
renderMathInElement(document.getElementById("content"), {
129
  ignoredClasses: ["no-math"]
130
});
131
</script>
132
```
133

134
### Integration with Frameworks
135

136
Auto-render works with modern frameworks:
137

138
```typescript
139
// React useEffect
140
useEffect(() => {
141
  renderMathInElement(containerRef.current);
142
}, [content]);
143

144
// Vue mounted hook
145
mounted() {
146
  renderMathInElement(this.$el);
147
}
148

149
// Angular ngAfterViewInit
150
ngAfterViewInit() {
151
  renderMathInElement(this.elementRef.nativeElement);
152
}
153
```