0
# KaTeX
1
2
KaTeX is the fastest math typesetting library for the web. It renders TeX math expressions using pure CSS/HTML without relying on MathJax, enabling blazing-fast client-side and server-side math rendering with high-quality output that's identical across all browsers.
3
4
## Package Information
5
6
- **Package Name**: katex
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install katex`
10
11
## Core Imports
12
13
```typescript
14
import katex from "katex";
15
```
16
17
For ESM named imports:
18
19
```typescript
20
import { render, renderToString, ParseError } from "katex";
21
```
22
23
For CommonJS:
24
25
```javascript
26
const katex = require("katex");
27
const { render, renderToString } = require("katex");
28
```
29
30
## Basic Usage
31
32
```typescript
33
import katex from "katex";
34
35
// Render to DOM element
36
const element = document.getElementById("math");
37
katex.render("c = \\pm\\sqrt{a^2 + b^2}", element, {
38
throwOnError: false
39
});
40
41
// Render to HTML string
42
const html = katex.renderToString("\\frac{1}{2}", {
43
displayMode: true
44
});
45
46
// Handle errors
47
try {
48
katex.render("\\invalid", element);
49
} catch (error) {
50
if (error instanceof katex.ParseError) {
51
console.log("Parse error at position:", error.position);
52
}
53
}
54
```
55
56
## Architecture
57
58
KaTeX is built around several key components:
59
60
- **Core Rendering Engine**: Fast TeX-to-HTML/MathML conversion with DOM and string output modes
61
- **Parser**: Recursive descent parser that converts TeX expressions into internal parse trees
62
- **Settings System**: Comprehensive configuration for output format, error handling, and LaTeX compatibility
63
- **Extension System**: Pluggable contrib modules for auto-rendering, chemistry, accessibility, and clipboard integration
64
- **CLI Interface**: Command-line tool for server-side rendering and batch processing
65
66
## Capabilities
67
68
### Core Rendering
69
70
Primary rendering functions that convert TeX expressions to DOM elements or HTML strings.
71
72
```typescript { .api }
73
function render(tex: string, element: HTMLElement, options?: KatexOptions): void;
74
function renderToString(tex: string, options?: KatexOptions): string;
75
```
76
77
[Core Rendering](./core-rendering.md)
78
79
### Auto-Rendering
80
81
Automatic math detection and rendering within HTML elements, supporting multiple delimiter types.
82
83
```typescript { .api }
84
function renderMathInElement(element: Element, options?: AutoRenderOptions): void;
85
86
interface AutoRenderOptions extends KatexOptions {
87
delimiters?: DelimiterConfig[];
88
ignoredTags?: string[];
89
ignoredClasses?: string[];
90
errorCallback?: (msg: string, err: Error) => void;
91
preProcess?: (math: string) => string;
92
}
93
```
94
95
[Auto-Rendering](./auto-rendering.md)
96
97
### Chemistry Rendering
98
99
Chemical equation and formula rendering through the mhchem extension.
100
101
```typescript { .api }
102
// Available as LaTeX macros when mhchem is imported:
103
// \ce{H2O} - Chemical equations and formulas
104
// \pu{1.2e3 kg*m/s^2} - Physical units
105
// \tripledash - Chemical bonds
106
```
107
108
[Chemistry Rendering](./chemistry.md)
109
110
### Configuration and Error Handling
111
112
Comprehensive options system and error handling for controlling output format and behavior.
113
114
```typescript { .api }
115
interface KatexOptions {
116
displayMode?: boolean;
117
output?: "html" | "mathml" | "htmlAndMathml";
118
throwOnError?: boolean;
119
errorColor?: string;
120
macros?: Record<string, string | object | ((context: any) => string | object)>;
121
strict?: boolean | "ignore" | "warn" | "error" | StrictFunction;
122
trust?: boolean | TrustFunction;
123
maxSize?: number;
124
maxExpand?: number;
125
// ... additional options
126
}
127
128
class ParseError extends Error {
129
name: "ParseError";
130
position: number;
131
length: number;
132
rawMessage: string;
133
}
134
```
135
136
[Configuration](./configuration.md)
137
138
### Accessibility
139
140
Screen reader support and accessibility string generation for math expressions.
141
142
```typescript { .api }
143
function renderA11yString(tex: string, settings?: KatexOptions): string;
144
```
145
146
[Accessibility](./accessibility.md)
147
148
### CLI Interface
149
150
Command-line interface for server-side rendering and batch processing.
151
152
```bash
153
# Basic usage
154
katex --input input.tex --output output.html
155
156
# With options
157
katex --display-mode --no-throw-on-error --error-color ff0000
158
```
159
160
[CLI Interface](./cli.md)
161
162
### Copy-TeX Extension
163
164
Clipboard integration for copying rendered math as TeX source code.
165
166
```typescript { .api }
167
import "katex/contrib/copy-tex";
168
// Automatically enhances copy behavior for .katex elements
169
```
170
171
[Copy-TeX Extension](./copy-tex.md)
172
173
### MathTeX Script Type Extension
174
175
Automatic rendering of `<script type="math/tex">` elements for CMS integration.
176
177
```typescript { .api }
178
import "katex/contrib/mathtex-script-type";
179
// Automatically processes all script[type*="math/tex"] elements
180
```
181
182
[MathTeX Script Type](./mathtex-script-type.md)
183
184
### Advanced APIs
185
186
Internal and advanced functions for custom integrations and extensions.
187
188
```typescript { .api }
189
function __parse(expression: string, options: KatexOptions): AnyParseNode[];
190
function __renderToDomTree(expression: string, options: KatexOptions): DomSpan;
191
function __renderToHTMLTree(expression: string, options: KatexOptions): DomSpan;
192
function __setFontMetrics(fontMetrics: Record<string, FontMetrics>): void;
193
function __defineSymbol(mode: string, font: string, name: string, replace: string, mathclass?: string): void;
194
function __defineFunction(funcName: string, definition: FunctionDefinition): void;
195
function __defineMacro(name: string, body: string, numArgs?: number): void;
196
```
197
198
[Advanced APIs](./advanced-apis.md)
199
200
## Types
201
202
```typescript { .api }
203
interface KatexOptions {
204
displayMode?: boolean;
205
output?: "html" | "mathml" | "htmlAndMathml";
206
leqno?: boolean;
207
fleqn?: boolean;
208
throwOnError?: boolean;
209
errorColor?: string;
210
macros?: Record<string, string | object | ((macroExpander: object) => string | object)>;
211
minRuleThickness?: number;
212
colorIsTextColor?: boolean;
213
maxSize?: number;
214
maxExpand?: number;
215
strict?: boolean | "ignore" | "warn" | "error" | StrictFunction;
216
trust?: boolean | TrustFunction;
217
globalGroup?: boolean;
218
}
219
220
type StrictFunction = (
221
errorCode: "unknownSymbol" | "unicodeTextInMathMode" | "mathVsTextUnits" | "commentAtEnd" | "htmlExtension" | "newLineInDisplayMode",
222
errorMsg: string,
223
token: Token
224
) => boolean | "error" | "warn" | "ignore" | undefined;
225
226
type TrustContext =
227
| { command: "\\url", url: string, protocol?: string }
228
| { command: "\\href", url: string, protocol?: string }
229
| { command: "\\includegraphics", url: string, protocol?: string }
230
| { command: "\\htmlClass", class: string }
231
| { command: "\\htmlId", id: string }
232
| { command: "\\htmlStyle", style: string }
233
| { command: "\\htmlData", attributes: Record<string, string> };
234
235
type TrustFunction = (context: TrustContext) => boolean;
236
237
class ParseError extends Error {
238
name: "ParseError";
239
position: number;
240
length: number;
241
rawMessage: string;
242
message: string;
243
constructor(message: string, token?: object);
244
}
245
246
interface Token {
247
text: string;
248
loc: SourceLocation | undefined;
249
noexpand?: boolean;
250
treatAsRelax?: boolean;
251
}
252
253
interface SourceLocation {
254
start: number;
255
end: number;
256
lexer: Lexer;
257
}
258
259
interface Lexer {
260
input: string;
261
tokenRegex: RegExp;
262
settings: Required<KatexOptions>;
263
catcodes: Record<string, number>;
264
}
265
```