0
# Chemistry Rendering
1

2
Chemical equation and formula rendering through the mhchem extension, providing comprehensive support for chemical notation, reactions, and physical units.
3

4
## Import
5

6
```typescript
7
import "katex/contrib/mhchem";
8
```
9

10
For CommonJS:
11

12
```javascript
13
require("katex/contrib/mhchem");
14
```
15

16
## Capabilities
17

18
### Chemical Equations (\ce)
19

20
Renders chemical formulas, equations, and reactions with proper formatting.
21

22
```typescript { .api }
23
// Available as LaTeX macro after importing mhchem:
24
// \ce{chemical_expression}
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import katex from "katex";
31
import "katex/contrib/mhchem";
32

33
// Simple chemical formulas
34
katex.render("\\ce{H2O}", element);                    // Water
35
katex.render("\\ce{CaCl2}", element);                  // Calcium chloride
36
katex.render("\\ce{H2SO4}", element);                  // Sulfuric acid
37

38
// Chemical reactions
39
katex.render("\\ce{2H2 + O2 -> 2H2O}", element);      // Combustion
40
katex.render("\\ce{A + B <=> C + D}", element);       // Equilibrium
41
katex.render("\\ce{Fe^3+ + 3OH- -> Fe(OH)3}", element); // Precipitation
42

43
// Complex reactions with conditions
44
katex.render("\\ce{CaCO3 ->[\\Delta] CaO + CO2}", element);
45
katex.render("\\ce{A ->[H+][\\ce{Hg^2+}] B}", element);
46

47
// States of aggregation
48
katex.render("\\ce{NaCl(aq) + AgNO3(aq) -> AgCl(s) + NaNO3(aq)}", element);
49
katex.render("\\ce{H2O(l) <=> H2O(g)}", element);
50

51
// Charges and oxidation states
52
katex.render("\\ce{Fe^{II}Fe^{III}2O4}", element);    // Mixed oxidation states
53
katex.render("\\ce{Cr^{VI}O4^2-}", element);          // Chromate ion
54

55
// Bonds
56
katex.render("\\ce{C-C}", element);                    // Single bond
57
katex.render("\\ce{C=C}", element);                    // Double bond
58
katex.render("\\ce{C#C}", element);                    // Triple bond
59
katex.render("\\ce{C~C}", element);                    // Aromatic bond
60
```
61

62
### Physical Units (\pu)
63

64
Renders physical quantities with proper unit formatting and spacing.
65

66
```typescript { .api }
67
// Available as LaTeX macro after importing mhchem:
68
// \pu{physical_unit_expression}
69
```
70

71
**Usage Examples:**
72

73
```typescript
74
import katex from "katex";
75
import "katex/contrib/mhchem";
76

77
// Basic units
78
katex.render("\\pu{123 kJ/mol}", element);            // Energy per mole
79
katex.render("\\pu{298.15 K}", element);              // Temperature
80
katex.render("\\pu{1.23e-4 mol*L^-1}", element);     // Concentration
81

82
// Complex units
83
katex.render("\\pu{9.81 m*s^-2}", element);          // Acceleration
84
katex.render("\\pu{1.38e-23 J*K^-1}", element);      // Boltzmann constant
85
katex.render("\\pu{6.022e23 mol^-1}", element);      // Avogadro's number
86

87
// Temperature units
88
katex.render("\\pu{25 \\degree C}", element);         // Celsius
89
katex.render("\\pu{77 \\degree F}", element);         // Fahrenheit
90

91
// Fractions
92
katex.render("\\pu{55.4 g//mol}", element);          // Alternative fraction
93
katex.render("\\pu{RT//F}", element);                // Variables in fractions
94

95
// Ranges and uncertainties
96
katex.render("\\pu{1.23(4) g*cm^-3}", element);     // Uncertainty
97
katex.render("\\pu{(1.23 +- 0.04) g*cm^-3}", element); // Plus-minus
98
```
99

100
### Chemical Bonds (\tripledash)
101

102
Special bond notation for chemical structures.
103

104
```typescript { .api }
105
// Available as LaTeX macro after importing mhchem:
106
// \tripledash
107
```
108

109
**Usage Example:**
110

111
```typescript
112
import katex from "katex";
113
import "katex/contrib/mhchem";
114

115
// Bond notation in chemical structures
116
katex.render("\\ce{C~\\tripledash~C}", element);
117
```
118

119
### Supported Chemical Notation
120

121
The mhchem extension supports:
122

123
- **Elements**: All periodic table elements (H, He, Li, etc.)
124
- **Formulas**: Subscripts, superscripts, charges (H2SO4, Ca2+, OH-)
125
- **Reactions**: Arrows, equilibrium, conditions (A + B -> C, A <=> B)
126
- **States**: Solid (s), liquid (l), gas (g), aqueous (aq)
127
- **Bonds**: Single (-), double (=), triple (#), aromatic (~)
128
- **Isotopes**: Mass numbers (^14C, ^235U)
129
- **Stoichiometry**: Coefficients and fractions (2H2O, 1/2O2)
130
- **Conditions**: Temperature, pressure, catalysts ([Delta], [H+])
131

132
### Error Handling
133

134
Chemical expressions follow the same error handling as regular KaTeX:
135

136
```typescript
137
import katex from "katex";
138
import "katex/contrib/mhchem";
139

140
try {
141
  katex.render("\\ce{InvalidFormula[]}", element);
142
} catch (error) {
143
  if (error instanceof katex.ParseError) {
144
    console.log("Chemical notation error:", error.message);
145
  }
146
}
147

148
// Or with error suppression
149
katex.render("\\ce{InvalidFormula[]}", element, {
150
  throwOnError: false,
151
  errorColor: "#ff0000"
152
});
153
```
154

155
### Integration with Auto-Render
156

157
mhchem works seamlessly with auto-render:
158

159
```html
160
<div id="chemistry-content">
161
  <p>Water formula: \\(\\ce{H2O}\\)</p>
162
  <p>Combustion: $$\\ce{CH4 + 2O2 -> CO2 + 2H2O}$$</p>
163
  <p>Concentration: \\(\\pu{0.1 mol*L^-1}\\)</p>
164
</div>
165

166
<script>
167
import renderMathInElement from "katex/contrib/auto-render";
168
import "katex/contrib/mhchem";
169

170
renderMathInElement(document.getElementById("chemistry-content"));
171
</script>
172
```