he is published as an ECMAScript module with named exports:
import { decode, encode, escape, unescape } from 'he';// Or, to use the `he.*` style shown in the examples below:import * as he from 'he';
In a browser, using a <script type="module"> and a path to the package’s src/he.mjs:
<script type="module"> import * as he from './node_modules/he/src/he.mjs';</script>
In CommonJS code on Node.js versions that support require(esm), require('he') returns the module namespace object, so require('he').encode(…) works as well.
API
he.encode(text, options)
This function takes a string of text and encodes (by default) any symbols that aren’t printable ASCII symbols and &, <, >, ", ', and `, replacing them with character references.
However, enabling the strict option causes invalid code points to throw an exception. With strict enabled, he.encode either throws (if the input contains invalid code points) or returns a string of valid HTML.
The options object is optional. It recognizes the following properties:
The default value for the encodeEverything option is false. This means that encode() will not use any character references for printable ASCII symbols that don’t need escaping. Set it to true to encode every symbol in the input string. When set to true, this option takes precedence over allowUnsafeSymbols (i.e. setting the latter to true in such a case has no effect).
The default value for the strict option is false. This means that encode() will encode any HTML text content you feed it, even if it contains any symbols that cause parse errors. To throw an error when such invalid HTML is encountered, set the strict option to true. This option makes it possible to use he as part of HTML parsers and HTML validators.
// Using the global default setting (defaults to `false`, i.e. error-tolerant mode):he.encode('\x01');// → ''// Passing an `options` object to `encode`, to explicitly enable error-tolerant mode:he.encode('\x01', { strict: false,});// → ''// Passing an `options` object to `encode`, to explicitly enable strict mode:he.encode('\x01', { strict: true,});// → Parse error
allowUnsafeSymbols
The default value for the allowUnsafeSymbols option is false. This means that characters that are unsafe for use in HTML content (&, <, >, ", ', and `) will be encoded. When set to true, only non-ASCII characters will be encoded. If the encodeEverything option is set to true, this option will be ignored.
The global default setting can be overridden by modifying the he.encode.options object. This saves you from passing in an options object for every call to encode if you want to use the non-default setting.
The options object is optional. It recognizes the following properties:
isAttributeValue
The default value for the isAttributeValue option is false. This means that decode() will decode the string as if it were used in a text context in an HTML document. HTML has different rules for parsing character references in attribute values — set this option to true to treat the input string as if it were used as an attribute value.
// Using the global default setting (defaults to `false`, i.e. HTML text context):he.decode('foo&bar');// → 'foo&bar'// Passing an `options` object to `decode`, to explicitly assume an HTML text context:he.decode('foo&bar', { isAttributeValue: false,});// → 'foo&bar'// Passing an `options` object to `decode`, to explicitly assume an HTML attribute value context:he.decode('foo&bar', { isAttributeValue: true,});// → 'foo&bar'
strict
The default value for the strict option is false. This means that decode() will decode any HTML text content you feed it, even if it contains any entities that cause parse errors. To throw an error when such invalid HTML is encountered, set the strict option to true. This option makes it possible to use he as part of HTML parsers and HTML validators.
// Using the global default setting (defaults to `false`, i.e. error-tolerant mode):he.decode('foo&bar');// → 'foo&bar'// Passing an `options` object to `decode`, to explicitly enable error-tolerant mode:he.decode('foo&bar', { strict: false,});// → 'foo&bar'// Passing an `options` object to `decode`, to explicitly enable strict mode:he.decode('foo&bar', { strict: true,});// → Parse error
Overriding default decode options globally
The global default settings for the decode function can be overridden by modifying the he.decode.options object. This saves you from passing in an options object for every call to decode if you want to use a non-default setting.
// Read the global default setting:he.decode.options.isAttributeValue;// → `false` by default// Override the global default setting:he.decode.options.isAttributeValue = true;// Using the global default setting, which is now `true`:he.decode('foo&bar');// → 'foo&bar'
he.escape(text)
This function takes a string of text and escapes it for use in text contexts in XML or HTML documents. Only the following characters are escaped: &, <, >, ", ', and `.
Read a local text file, encode it for use in an HTML text context, and save the result to a new file:
$ he --encode < foo.txt > foo-escaped.html
Or do the same with an online text file:
$ curl -sL "http://git.io/HnfEaw" | he --encode > escaped.html
Or, the opposite — read a local file containing a snippet of HTML in a text context, decode it back to plain text, and save the result to a new file:
$ he --decode < foo-escaped.html > foo.txt
Or do the same with an online HTML snippet:
$ curl -sL "http://git.io/HnfEaw" | he --decode > decoded.txt
See he --help for the full list of options.
Support
he is an ES2022 module. It works in all modern browsers and in Node.js v22+. The CLI requires Node.js v22+.
Development
After cloning this repository, run npm install to install the development dependencies.
npm test runs the test suite using the built-in Node.js test runner.
npm run coverage prints a code coverage report.
npm run build regenerates data/*.json from data/entities.json and writes the generated src/data.mjs module, which src/he.mjs imports.
npm run fetch downloads the latest entities.json, derives the invalid code points and character reference overrides from the HTML and Infra Standards, and rebuilds. If the relevant spec prose changes, scripts/fetch-spec.mjs fails with an explanation instead of writing data.
npm run format formats the code using Oxfmt; npm run format:check verifies formatting.