Manual for: mhchem for MathJax, mhchem for KaTeX

Please ensure Internet access and enable JavaScript.

# mhchem for MathJax <br> mhchem for KaTeX

*mhchem* is a tool for writing beautiful chemical equations easily.

This is the manual for mhchem's input syntax (as implemented in JavaScript display engines for mathematics).

## Configuration

**[MathJax](*https://mathjax.org/)**: 
If you are configuring MathJax yourself, see this [JS Bin](https://jsbin.com/?html=%3C%21DOCTYPE%20html%3E%0A%3Chtml%3E%0A%3Chead%3E%0A%20%20%3Cmeta%20charset%3D%22utf-8%22%3E%0A%20%20%3Cmeta%20name%3D%22viewport%22%20content%3D%22width%3Ddevice-width%22%3E%0A%20%20%3Ctitle%3EMathJax%20%2B%20mhchem%20example%3C%2Ftitle%3E%0A%20%20%3Cscript%3E%0A%20%20%20%20window.MathJax%20%3D%20%7B%0A%20%20%20%20%20%20tex%3A%20%7B%0A%20%20%20%20%20%20%20%20%2F%2F%20inlineMath%3A%20%5B%5B%27%24%27%2C%20%27%24%27%5D%2C%20%5B%27%5C%5C%28%27%2C%20%27%5C%5C%29%27%5D%5D%2C%0A%20%20%20%20%20%20%20%20packages%3A%20%7B%27%5B%2B%5D%27%3A%20%5B%27mhchem%27%5D%7D%0A%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%20%20loader%3A%20%7Bload%3A%20%5B%27%5Btex%5D%2Fmhchem%27%5D%7D%2C%0A%20%20%20%20%7D%3B%0A%20%20%3C%2Fscript%3E%0A%20%20%3Cscript%20id%3D%22MathJax-script%22%20async%20src%3D%22https%3A%2F%2Fcdn.jsdelivr.net%2Fnpm%2Fmathjax%403%2Fes5%2Ftex-mml-chtml.js%22%3E%3C%2Fscript%3E%0A%3C%2Fhead%3E%0A%3Cbody%3E%0A%20%20%5C%28%5Cce%7B2H%20%2B%20O%20-%3E%20H2O%7D%5C%29%0A%3C%2Fbody%3E%0A%3C%2Fhtml%3E&live)
and the [MathJax documentation](http://docs.mathjax.org/en/latest/web/configuration.html) and the [extension page](http://docs.mathjax.org/en/latest/input/tex/extensions/mhchem.html).
<br>
**[KaTeX](*https://katex.org/)**:
See this [JS Bin](https://jsbin.com/?html=%3C%21DOCTYPE%20html%3E%0A%3Chtml%3E%0A%3Chead%3E%0A%20%20%3Cmeta%20charset%3D%22utf-8%22%3E%0A%20%20%3Cmeta%20name%3D%22viewport%22%20content%3D%22width%3Ddevice-width%22%3E%0A%20%20%3Ctitle%3EKaTeX%20%2B%20mhchem%20example%3C%2Ftitle%3E%0A%20%20%3Clink%20rel%3D%22stylesheet%22%20href%3D%22https%3A%2F%2Fcdn.jsdelivr.net%2Fnpm%2Fkatex%400.13.3%2Fdist%2Fkatex.min.css%22%20integrity%3D%22sha384-ThssJ7YtjywV52Gj4JE%2F1SQEDoMEckXyhkFVwaf4nDSm5OBlXeedVYjuuUd0Yua%2B%22%20crossorigin%3D%22anonymous%22%3E%0A%20%20%3Cscript%20defer%20src%3D%22https%3A%2F%2Fcdn.jsdelivr.net%2Fnpm%2Fkatex%400.13.3%2Fdist%2Fkatex.min.js%22%20integrity%3D%22sha384-Bi8OWqMXO1ta%2Ba4EPkZv7bYGIes7C3krGSZoTGNTAnAn5eYQc7IIXrJ%2F7ck1drAi%22%20crossorigin%3D%22anonymous%22%3E%3C%2Fscript%3E%0A%20%20%3Cscript%20defer%20src%3D%22https%3A%2F%2Fcdn.jsdelivr.net%2Fnpm%2Fkatex%400.13.3%2Fdist%2Fcontrib%2Fmhchem.min.js%22%20integrity%3D%22sha384-LIgAiYlGSAdpNC9%2BYDjDPF6JeS%2FRRIumtNo0CmyQERZ%2F%2Bg0h9MbuYQwf%2F5pQ4Y4M%22%20crossorigin%3D%22anonymous%22%3E%3C%2Fscript%3E%0A%20%20%3Cscript%20defer%20src%3D%22https%3A%2F%2Fcdn.jsdelivr.net%2Fnpm%2Fkatex%400.13.3%2Fdist%2Fcontrib%2Fauto-render.min.js%22%20integrity%3D%22sha384-vZTG03m%2B2yp6N6BNi5iM4rW4oIwk5DfcNdFfxkk9ZWpDriOkXX8voJBFrAO7MpVl%22%20crossorigin%3D%22anonymous%22%0A%20%20%20%20%20%20onload%3D%22renderMathInElement%28document.body%29%3B%22%3E%3C%2Fscript%3E%0A%3C%2Fhead%3E%0A%3Cbody%3E%0A%20%20%5C%28%5Cce%7B2H%20%2B%20O%20-%3E%20H2O%7D%5C%29%3Cbr%3E%0A%3C%2Fbody%3E%0A%3C%2Fhtml%3E&live) and
the [KaTeX documentation](https://katex.org/docs/browser.html) and the [extension page](https://github.com/KaTeX/KaTeX/blob/master/contrib/mhchem/README.md).
<br>
(**LaTeX**):
The features of the LaTeX package differ slightly from the JavaScript-based implementation. [Manual for mhchem for LaTeX](http://mirrors.ctan.org/macros/latex/contrib/mhchem/mhchem.pdf)
<br>
**[Chemistry StackExchange](*https://chemistry.stackexchange.com)**: Just write `$\ce{H2O}$`. On the [other StackExchange sites with MathJax](*https://meta.stackexchange.com/a/216607) it is enough to write `$\require{mhchem}$` once per question/answer.
**[Joplin](*https://joplinapp.org/), [Typora](*https://typora.io/)**: Just write `$\ce{H2O}$`.
**[Notion](*https://notion.so/)**: Write `$$\ce{H2O}$$`.
**[Anki](*https://apps.ankiweb.net/)**: Just write `$\ce{H2O}$`.

</div>

## Chemical Equations (ce)
:::: CO2 + C -> 2 CO
:::: Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-
::::$ C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}

## Chemical Formulae
:::: H2O
:::: Sb2O3

## Charges
:::: H+
:::: CrO4^2-
:::: [AgCl2]-
:::: Y^99+
:::: Y^{99+}

## Stoichiometric Numbers
:::: 2 H2O
:::: 2H2O
:::: 0.5 H2O
:::: 1/2 H2O
:::: (1/2) H2O % IUPAC Green Book
:::: $n$ H2O

## Nuclides, Isotopes
:::: ^{227}_{90}Th+
:::: ^227_90Th+
:::: ^{0}_{-1}n^{-}
:::: ^0_-1n-
It might be ambiguous whether a superscript belongs to the left or right element. There is automatic detection (digits only = mass number = belongs to right side), but to make sure you can type `{}` as a separator.
:::: H{}^3HO
:::: H^3HO

## Reaction Arrows
:::: A -> B
:::: A <- B
:::: A <-> B % not to be used according to IUPAC and ACS
:::: A <--> B
:::: A <=> B
:::: A <=>> B
:::: A <<=> B
Each arrow can take two optional arguments: one for above and one for below. The arrow arguments use the same input syntax as the `\ce` command.
:::: A ->[H2O] B % chemistry
:::: A ->[{text above}][{text below}] B % upright text, see below
:::: A ->[$x$][$x_i$] B % italic math, see below
Unfortunately, MathJax [cannot stretch](https://github.com/mathjax/MathJax/issues/1491) `<-->`, `<=>`, `<=>>` and `<<=>` arrows properly. All the arrows do stretch in LaTeX and KaTeX.

## Parentheses, Brackets, Braces
Use parentheses `( )` and brackets `[ ]` normally. Write braces as `\{ \}`.
:::: (NH4)2S
:::: [\{(X2)3\}2]^3+
For large parentheses, `\left` and `\right` macros need to be in the same math environment, so you might have to put `\ce` into `$` into `\ce`, but that's fine.
:::: CH4 + 2 $\left( \ce{O2 + 79/21 N2} \right)$

## States of Aggregation <small>(not fully supported for LaTeX yet)</small>
:::: H2(aq) % IUPAC recommendation
:::: CO3^2-_{(aq)} % not IUPAC-conform, not ACS-conform
:::: NaOH(aq,$\infty$)

## Crystal Systems <small>(not fully supported for LaTeX yet)</small>
:::: ZnS($c$)
:::: ZnS(\ca$c$) % Circa, tilde

## Variables like __*x*, *n*, 2*n*+1__
Typographical conventions say that variables are typeset in an italic font, while other entities (like chemical elements) are typeset in an upright font. mhchem tries to recognize common patterns and use the correct (italic) font, like the *x* and *n* in the following examples.
:::: NO_x
:::: Fe^n+
:::: x Na(NH4)HPO4 ->[\Delta] (NaPO3)_x + x NH3 ^ + x H2O
If a more complex term is not properly recognized, you can switch to math mode (= italics) explicitly.

## Greek Characters
Just write `\alpha` etc. Typographical conventions say that variables are typeset in an italic font, while other entities (like chemical elements) are typeset in an upright font. In the following examples, the Greek character is *not* a variable that stands for a number, therefore an upright font *should* be used. Unfortunately, neither MathJax nor KaTeX [support](https://github.com/mathjax/mathjax-docs/wiki/Non-italic-(upright)-greek-letters) upright lower-case Greek characters.
:::: \mu-Cl
:::: [Pt(\eta^2-C2H4)Cl3]-
Spaces after a greek character are ignored. This is standard TeX behavior. Insert `{}` to get the desired output.
:::: \beta +
:::: ^40_18Ar + \gamma{} + \nu_e

## (Italic) Math
By using `$...$` you can escape to math mode.
:::: NaOH(aq,$\infty$)
:::: Fe(CN)_{$\frac{6}{2}$}
:::: X_{$i$}^{$x$}
:::: X_$i$^$x$
(With *mhchem for LaTex* there is a difference between `$...$` and `${...}$`. But because neither MathJax nor KaTeX have a text font, both inputs will yield identical results there.)

## Italic Text
With the same mechanism you can mimic an italic text font.
:::: $cis${-}[PtCl2(NH3)2]
:::: CuS($hP12$) % Pearson Symbol
Spaces will be ignored. Use a `~` when you need to typeset a space.

## Upright Text, Escape Parsing
Enclose upright text with `{...}`.
:::: {Gluconic Acid} + H2O2
:::: X_{{red}}
With the same mechanism, you can escape parsing, for instance if you need a simple hyphen (that should not become a bond).
:::: {(+)}_589{-}[Co(en)3]Cl3

## Bonds
:::: C6H5-CHO
:::: A-B=C#D
mhchem tries to differentiate whether `\ce{-}` should be a bond, a charge or a hyphen.
:::: A\bond{-}B\bond{=}C\bond{#}D
:::: A\bond{1}B\bond{2}C\bond{3}D
:::: A\bond{~}B\bond{~-}C
:::: A\bond{~--}B\bond{~=}C\bond{-~-}D
:::: A\bond{...}B\bond{....}C
:::: A\bond{->}B\bond{<-}C

## Addition Compounds
:::: KCr(SO4)2*12H2O
:::: KCr(SO4)2.12H2O
:::: KCr(SO4)2 * 12 H2O

## Oxidation States
:::: Fe^{II}Fe^{III}2O4

## Unpaired Electrons, Radical Dots
:::: OCO^{.-}
:::: NO^{(2.)-}

## Kröger-Vink Notation <small>(not supported for LaTeX yet)</small>
:::: Li^x_{Li,1-2x}Mg^._{Li,x}$V$'_{Li,x}Cl^x_{Cl}
:::: O''_{i,x}
:::: M^{..}_i
:::: $V$^{4'}_{Ti}
:::: V_{V,1}C_{C,0.8}$V$_{C,0.2} % upright V = Vanadium, italic V = vacancy

## Equation Operators
:::: A + B
:::: A - B % not to be confused with bonds
:::: A = B % not to be confused with bonds
:::: A \pm B

## Precipitate and Gas
:::: SO4^2- + Ba^2+ -> BaSO4 v
:::: A v B (v) -> B ^ B (^)

## Other Symbols and Shortcuts <small>(not fully supported for LaTeX yet)</small>
:::: NO^* % Excited state
:::: 1s^2-N % Orbitals
:::: n-Pr
:::: iPr
:::: \ca Fe
:::: A, B, C; F % Punctuation
:::: {and others}

## Complex Examples
:::: Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteres Hydroxid}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{Hydroxozikat}}{\ce{[Zn(OH)4]^2-}}$
:::: $K = \frac{[\ce{Hg^2+}][\ce{Hg}]}{[\ce{Hg2^2+}]}$
:::: $K = \ce{\frac{[Hg^2+][Hg]}{[Hg2^2+]}}$
:::: Hg^2+ ->[I-]  $\underset{\mathrm{red}}{\ce{HgI2}}$  ->[I-]  $\underset{\mathrm{red}}{\ce{[Hg^{II}I4]^2-}}$

<a name="pu"></a>
## Physical Units (pu) <small>(MathJax or KaTeX only, not for LaTeX)</small>
::::pu 123 kJ
::::pu 123 mm2
There are two conventions regarding the multiplication within units.
::::pu 123 J s
::::pu 123 J*s
There are four conventions regarding divisions.
::::pu 123 kJ/mol
::::pu 123 kJ//mol
::::pu 123 kJ mol-1
::::pu 123 kJ*mol-1
There are four main conventions for writing numbers in scientific notation.
::::pu 1.2e3 kJ
::::pu 1,2e3 kJ
::::pu 1.2E3 kJ
::::pu 1,2E3 kJ

If you need more control than is offered here, take a look at the siunitx extension.

## Compatibility with mhchem for LaTeX
Most of these examples work identically for *mhchem for MathJax*, *mhchem for KaTeX* and *mhchem and LaTeX*. Exceptions are indicated. Also, some edge-cases may render differently. I will try to minimize the differences in the future. But even then, the MathJax and KaTeX versions will always be more tolerant of sloppy input (e.g. a missing space) than *mhchem for LaTeX*.

## Contact and Support
If you have a question and cannot find an answer---neither here nor with a web search---then
- mail me (:myaddress:) or
- create an GitHub issue (https://github.com/mhchem/MathJax-mhchem/issues) or
- ask at StackExchange (http://meta.chemistry.stackexchange.com/) with the mhchem tag.

## Test Drive
:testdrive: