Escape LaTeX Special Characters

1.2.0 · active · verified Sun Apr 19

escape-latex is a JavaScript utility for sanitizing strings by escaping LaTeX special characters, making them safe for inclusion in LaTeX documents. The current stable version is 1.2.0. As a focused utility, it typically has an infrequent release cadence, with updates primarily for bug fixes or minor enhancements. Its key differentiators include the ability to selectively escape characters that would simply malform LaTeX (`# $ % & \ ^ _ { }`) versus those that affect formatting (spaces, en-dashes, em-dashes) via the `preserveFormatting` option. Furthermore, it provides an `escapeMapFn` callback, allowing developers to fully customize or extend the character-to-escape mapping based on specific LaTeX requirements, offering flexibility beyond standard escaping mechanisms. It is designed for use in Node.js environments.

Common errors

```
LaTeX Error: Missing $ inserted
```
cause Input string contains unescaped math mode delimiters like '$' or '^' outside of a math environment.

fix The default `escape-latex` function will escape these. Ensure you are passing the string through `lescape()` before including it in your LaTeX document.
```
My output string 'Hello   World' is rendered as 'Hello World' in LaTeX, I expected three spaces.
```
cause By default, `escape-latex` does not escape whitespace characters, and LaTeX itself collapses multiple spaces into a single space.

fix To preserve multiple spaces, tabs, and other formatting characters, call `lescape("Hello World", { preserveFormatting: true });`. This will convert spaces into non-breaking space commands (`~`).
```
Specific character (e.g., '€', '£') is not being escaped or is causing issues in LaTeX.
```
cause The default escape map does not include all possible special characters from various encodings, or you have a custom character you wish to treat specially.

fix Use the `escapeMapFn` option to extend or modify the character escape mapping. For example, `escapeMapFn: (d, f) => { d['€'] = '\euro{}'; return Object.assign({}, d, f); }`.

Warnings

breaking En-dash and em-dash characters are no longer escaped by default, changing previous behavior.
Fix: To re-enable en-dash and em-dash escaping, set the `preserveFormatting` option to `true` when calling `escape-latex`.
gotcha By default, the library only escapes characters that would malform LaTeX syntax. It does not preserve whitespace or other formatting characters (like dashes or tabs) that LaTeX might normalize or interpret differently.
Fix: If the final LaTeX output needs to closely resemble the input string's formatting, including multiple spaces, tabs, and specific dash representations, set the `preserveFormatting` option to `true`.
gotcha The `escapeMapFn` allows for custom escape logic, but incorrect modifications can lead to malformed LaTeX or unintended output.
Fix: When using `escapeMapFn`, always ensure that the custom mappings produce valid LaTeX syntax. It's recommended to combine your custom escapes with `defaultEscapes` and `formattingEscapes` using `Object.assign({}, defaultEscapes, formattingEscapes)` to avoid losing default escaping behavior.

Install

npm install escape-latex npm
yarn add escape-latex yarn
pnpm add escape-latex pnpm

Imports

lescape
wrong:
```
import { lescape } from 'escape-latex';
```
correct:
```
import lescape from 'escape-latex';
```
The library exports a default function, not a named export. ESM environments should use a default import.
lescape
wrong:
```
const { lescape } = require('escape-latex');
```
correct:
```
const lescape = require('escape-latex');
```
In CommonJS, the module's default export is directly assigned to the variable.
options
wrong:
```
lescape(input, true);
```
correct:
```
lescape(input, { preserveFormatting: true });
```
Configuration is passed as an options object, not direct boolean arguments, especially for `preserveFormatting`.

Quickstart

Demonstrates basic, formatting-preserving, and custom character escaping using `escape-latex` in an ESM context.

import lescape from 'escape-latex';

// Basic escaping: only characters that would malform LaTeX are escaped.
// Note: multiple spaces might be collapsed by LaTeX.
const basicEscaped = lescape("Hello #World! This is $money & more.");
console.log('Basic Escaped:', basicEscaped);

// Preserving formatting: also escapes spaces, tabs, en-dashes, em-dashes.
// LaTeX will render multiple spaces as multiple non-breaking spaces.
const formattedEscaped = lescape("Hello   World -- with dashes --- and tabs\t!", { preserveFormatting: true });
console.log('Formatted Escaped:', formattedEscaped);

// Custom escaping: use escapeMapFn to define specific character mappings.
const customEscaped = lescape("Custom! @ symbol.", {
  escapeMapFn: (defaultEscapes, formattingEscapes) => {
    // Add an escape for '@' symbol
    defaultEscapes['@'] = '\\at{}'; 
    return Object.assign({}, defaultEscapes, formattingEscapes);
  }
});
console.log('Custom Escaped:', customEscaped);

/*
Example Output:
Basic Escaped: Hello \#World! This is \$money \& more.
Formatted Escaped: Hello~~~World~--~with~dashes~---~and~tabs\\t!
Custom Escaped: Custom! \at{} symbol.
*/

view raw JSON →