0
# Configuration
1

2
Comprehensive options system and error handling for controlling output format, LaTeX compatibility, security, and rendering behavior.
3

4
## Capabilities
5

6
### Core Configuration Options
7

8
Main rendering options that control output format and display behavior.
9

10
```typescript { .api }
11
interface KatexOptions {
12
  /** Render in display mode (centered, larger operators) vs inline mode */
13
  displayMode?: boolean; // default: false
14
  
15
  /** Output format for rendered math */
16
  output?: "html" | "mathml" | "htmlAndMathml"; // default: "htmlAndMathml"
17
  
18
  /** Render equation tags on the left (like \usepackage[leqno]{amsmath}) */
19
  leqno?: boolean; // default: false
20
  
21
  /** Render display math flush left with 2em margin */
22
  fleqn?: boolean; // default: false
23
}
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import katex from "katex";
30

31
// Display mode for block equations
32
katex.render("\\sum_{i=1}^n i^2", element, {
33
  displayMode: true
34
});
35

36
// HTML-only output (no MathML for accessibility)
37
const html = katex.renderToString("E = mc^2", {
38
  output: "html"
39
});
40

41
// MathML-only output
42
const mathml = katex.renderToString("\\frac{1}{2}", {
43
  output: "mathml"
44
});
45

46
// Left-aligned display math
47
katex.render("\\int_0^\\infty e^{-x^2} dx", element, {
48
  displayMode: true,
49
  fleqn: true
50
});
51
```
52

53
### Error Handling Configuration
54

55
Options for controlling error behavior and appearance.
56

57
```typescript { .api }
58
interface ErrorOptions {
59
  /** Whether to throw ParseError exceptions or render error text */
60
  throwOnError?: boolean; // default: true
61
  
62
  /** Color for error text when throwOnError is false */
63
  errorColor?: string; // default: "#cc0000"
64
}
65
```
66

67
**Usage Examples:**
68

69
```typescript
70
import katex from "katex";
71

72
// Suppress errors and show red error text
73
katex.render("\\invalid", element, {
74
  throwOnError: false,
75
  errorColor: "#ff6b6b"
76
});
77

78
// Custom error handling
79
try {
80
  katex.render("\\badcommand", element, {
81
    throwOnError: true
82
  });
83
} catch (error) {
84
  if (error instanceof katex.ParseError) {
85
    element.innerHTML = `<span style="color: red;">Math Error: ${error.rawMessage}</span>`;
86
  }
87
}
88
```
89

90
### Macro System
91

92
Custom macro definitions for extending TeX functionality.
93

94
```typescript { .api }
95
interface MacroOptions {
96
  /** Custom macro definitions */
97
  macros?: Record<string, string | object | MacroFunction>;
98
}
99

100
type MacroFunction = (macroExpander: object) => string | object;
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
import katex from "katex";
107

108
// String macros
109
katex.render("\\RR", element, {
110
  macros: {
111
    "\\RR": "\\mathbb{R}",
112
    "\\NN": "\\mathbb{N}",
113
    "\\d": "\\mathrm{d}"
114
  }
115
});
116

117
// Parameterized macros
118
katex.render("\\diff{f}{x}", element, {
119
  macros: {
120
    "\\diff": "\\frac{\\mathrm{d}#1}{\\mathrm{d}#2}"
121
  }
122
});
123

124
// Function macros (advanced)
125
const options = {
126
  macros: {
127
    "\\vec": (context) => {
128
      return "\\overrightarrow{" + context.consumeArgs(1)[0] + "}";
129
    }
130
  }
131
};
132
```
133

134
### LaTeX Compatibility and Security
135

136
Options for LaTeX faithfulness and input validation.
137

138
```typescript { .api }
139
interface CompatibilityOptions {
140
  /** LaTeX compatibility mode */
141
  strict?: boolean | "ignore" | "warn" | "error" | StrictFunction; // default: "warn"
142
  
143
  /** Trust input for HTML features like \url and \href */
144
  trust?: boolean | TrustFunction; // default: false
145
  
146
  /** Whether \color behaves like LaTeX's \textcolor */
147
  colorIsTextColor?: boolean; // default: false
148
}
149

150
type StrictFunction = (
151
  errorCode: "unknownSymbol" | "unicodeTextInMathMode" | "mathVsTextUnits" | 
152
            "commentAtEnd" | "htmlExtension" | "newLineInDisplayMode",
153
  errorMsg: string,
154
  token: Token
155
) => boolean | "error" | "warn" | "ignore" | undefined;
156

157
type TrustFunction = (context: TrustContext) => boolean;
158

159
type TrustContext = 
160
  | { command: "\\url", url: string, protocol?: string }
161
  | { command: "\\href", url: string, protocol?: string }
162
  | { command: "\\includegraphics", url: string, protocol?: string }
163
  | { command: "\\htmlClass", class: string }
164
  | { command: "\\htmlId", id: string }
165
  | { command: "\\htmlStyle", style: string }
166
  | { command: "\\htmlData", attributes: Record<string, string> };
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
import katex from "katex";
173

174
// Strict LaTeX mode (throws on non-LaTeX features)
175
katex.render("$x$", element, {
176
  strict: "error" // Will throw on $ delimiters (non-LaTeX)
177
});
178

179
// Custom strict handling
180
katex.render("\\unicode{0x1D400}", element, {
181
  strict: (errorCode, errorMsg, token) => {
182
    if (errorCode === "unknownSymbol") {
183
      console.warn("Unknown symbol:", errorMsg);
184
      return "ignore";
185
    }
186
    return "warn";
187
  }
188
});
189

190
// Trust specific URLs
191
katex.render("\\href{https://example.com}{link}", element, {
192
  trust: (context) => {
193
    if (context.command === "\\href") {
194
      return context.protocol === "https:";
195
    }
196
    return false;
197
  }
198
});
199

200
// Trust all input (use with caution)
201
katex.render("\\url{https://example.com}", element, {
202
  trust: true
203
});
204
```
205

206
### Performance and Limits
207

208
Options for controlling rendering performance and resource usage.
209

210
```typescript { .api }
211
interface PerformanceOptions {
212
  /** Maximum element size in ems (default: Infinity) */
213
  maxSize?: number;
214
  
215
  /** Maximum macro expansions to prevent infinite loops */
216
  maxExpand?: number; // default: 1000
217
  
218
  /** Minimum thickness for rules and lines in ems */
219
  minRuleThickness?: number;
220
  
221
  /** Run in global group (macros persist across renders) */
222
  globalGroup?: boolean; // default: false
223
}
224
```
225

226
**Usage Examples:**
227

228
```typescript
229
import katex from "katex";
230

231
// Limit element sizes
232
katex.render("\\rule{1000em}{1000em}", element, {
233
  maxSize: 10 // Caps at 10em
234
});
235

236
// Limit macro expansions
237
katex.render("\\def\\a{\\a}\\a", element, {
238
  maxExpand: 100 // Prevents infinite recursion
239
});
240

241
// Set minimum line thickness
242
katex.render("\\frac{1}{2}", element, {
243
  minRuleThickness: 0.05 // Ensures visible fraction line
244
});
245

246
// Global macro definitions
247
katex.render("\\gdef\\R{\\mathbb{R}} \\R", element, {
248
  globalGroup: true,
249
  macros: {} // Macros persist and can be reused
250
});
251
```
252

253
### Settings Schema
254

255
KaTeX exposes its complete settings schema for introspection:
256

257
```typescript { .api }
258
const SETTINGS_SCHEMA: Record<string, OptionSchema>;
259

260
interface OptionSchema {
261
  type: string | string[] | { enum: string[] };
262
  default?: any;
263
  description?: string;
264
  processor?: (value: any) => any;
265
  cli?: string | false;
266
  cliDescription?: string;
267
  cliProcessor?: (value: any, previous?: any) => any;
268
}
269
```
270

271
**Usage Example:**
272

273
```typescript
274
import katex from "katex";
275

276
// Inspect available options
277
console.log("Available KaTeX options:", Object.keys(katex.SETTINGS_SCHEMA));
278

279
// Get option details
280
const displayModeSchema = katex.SETTINGS_SCHEMA.displayMode;
281
console.log("Display mode type:", displayModeSchema.type);
282
console.log("Display mode default:", displayModeSchema.default);
283
```