{"id":10812,"library":"escape-latex","title":"Escape LaTeX Special Characters","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/dangmai/escape-latex","tags":["javascript","latex","escape"],"install":[{"cmd":"npm install escape-latex","lang":"bash","label":"npm"},{"cmd":"yarn add escape-latex","lang":"bash","label":"yarn"},{"cmd":"pnpm add escape-latex","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library exports a default function, not a named export. ESM environments should use a default import.","wrong":"import { lescape } from 'escape-latex';","symbol":"lescape","correct":"import lescape from 'escape-latex';"},{"note":"In CommonJS, the module's default export is directly assigned to the variable.","wrong":"const { lescape } = require('escape-latex');","symbol":"lescape","correct":"const lescape = require('escape-latex');"},{"note":"Configuration is passed as an options object, not direct boolean arguments, especially for `preserveFormatting`.","wrong":"lescape(input, true);","symbol":"options","correct":"lescape(input, { preserveFormatting: true });"}],"quickstart":{"code":"import lescape from 'escape-latex';\n\n// Basic escaping: only characters that would malform LaTeX are escaped.\n// Note: multiple spaces might be collapsed by LaTeX.\nconst basicEscaped = lescape(\"Hello #World! This is $money & more.\");\nconsole.log('Basic Escaped:', basicEscaped);\n\n// Preserving formatting: also escapes spaces, tabs, en-dashes, em-dashes.\n// LaTeX will render multiple spaces as multiple non-breaking spaces.\nconst formattedEscaped = lescape(\"Hello   World -- with dashes --- and tabs\\t!\", { preserveFormatting: true });\nconsole.log('Formatted Escaped:', formattedEscaped);\n\n// Custom escaping: use escapeMapFn to define specific character mappings.\nconst customEscaped = lescape(\"Custom! @ symbol.\", {\n  escapeMapFn: (defaultEscapes, formattingEscapes) => {\n    // Add an escape for '@' symbol\n    defaultEscapes['@'] = '\\\\at{}'; \n    return Object.assign({}, defaultEscapes, formattingEscapes);\n  }\n});\nconsole.log('Custom Escaped:', customEscaped);\n\n/*\nExample Output:\nBasic Escaped: Hello \\#World! This is \\$money \\& more.\nFormatted Escaped: Hello~~~World~--~with~dashes~---~and~tabs\\\\t!\nCustom Escaped: Custom! \\at{} symbol.\n*/","lang":"javascript","description":"Demonstrates basic, formatting-preserving, and custom character escaping using `escape-latex` in an ESM context."},"warnings":[{"fix":"To re-enable en-dash and em-dash escaping, set the `preserveFormatting` option to `true` when calling `escape-latex`.","message":"En-dash and em-dash characters are no longer escaped by default, changing previous behavior.","severity":"breaking","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `escapeMapFn` allows for custom escape logic, but incorrect modifications can lead to malformed LaTeX or unintended output.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"The default `escape-latex` function will escape these. Ensure you are passing the string through `lescape()` before including it in your LaTeX document.","cause":"Input string contains unescaped math mode delimiters like '$' or '^' outside of a math environment.","error":"LaTeX Error: Missing $ inserted"},{"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 (`~`).","cause":"By default, `escape-latex` does not escape whitespace characters, and LaTeX itself collapses multiple spaces into a single space.","error":"My output string 'Hello   World' is rendered as 'Hello World' in LaTeX, I expected three spaces."},{"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); }`.","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.","error":"Specific character (e.g., '€', '£') is not being escaped or is causing issues in LaTeX."}],"ecosystem":"npm"}