entities

entities

Encode & decode HTML & XML entities with ease & speed.

Features

• 😇 Tried and true: entities is used by many popular libraries; eg. htmlparser2, the official AWS SDK and commonmark use it to process HTML entities.
• ⚡️ Fast: entities is the fastest library for decoding HTML entities (as of September 2025); see performance.
• 🎛 Configurable: Get an output tailored for your needs. You are fine with UTF8? That'll save you some bytes. Prefer to only have ASCII characters? We can do that as well!

How to…

…install entities

npm install entities

…use entities

import * as entities from "entities";

// Encoding
entities.escapeUTF8("& ü"); // "& ü"
entities.encodeXML("& ü"); // "& ü"
entities.encodeHTML("& ü"); // "& ü"

// Decoding
entities.decodeXML("asdf & ÿ ü '"); // "asdf & ÿ ü '"
entities.decodeHTML("asdf & ÿ ü '"); // "asdf & ÿ ü '"

Performance

Benchmarked in September 2025 with Node v24.6.0 on Apple M2 using tinybench. Higher ops/s is better; avg (μs) is the mean time per operation. See scripts/benchmark.ts to reproduce.

Decoding

Library	Version	ops/s	avg (μs)	±%	slower
entities	7.0.0	5,838,416	175.57	0.06	—
html-entities	2.6.0	2,919,637	347.77	0.33	50.0%
he	1.2.0	2,318,438	446.48	0.70	60.3%
parse-entities	4.0.2	852,855	1,199.51	0.36	85.4%

Encoding

Library	Version	ops/s	avg (μs)	±%	slower
entities	7.0.0	2,770,115	368.09	0.11	—
html-entities	2.6.0	1,491,963	679.96	0.58	46.2%
he	1.2.0	481,278	2,118.25	0.61	82.6%

Escaping

Library	Version	ops/s	avg (μs)	±%	slower
entities	7.0.0	4,616,468	223.84	0.17	—
he	1.2.0	3,659,301	280.76	0.58	20.7%
html-entities	2.6.0	3,555,301	296.63	0.84	23.0%

Note: Micro-benchmarks may vary across machines and Node versions.

FAQ

What methods should I actually use to encode my documents?

If your target supports UTF-8, the escapeUTF8 method is going to be your best choice. Otherwise, use either encodeHTML or encodeXML based on whether you're dealing with an HTML or an XML document.

You can have a look at the options for the encode and decode methods to see everything you can configure.

When should I use strict decoding?

When strict decoding, entities not terminated with a semicolon will be ignored. This is helpful for decoding entities in legacy environments.

Why should I use entities instead of alternative modules?

As of September 2025, entities is faster than other modules. Still, this is not a differentiated space and other modules can catch up.

More importantly, you might already have entities in your dependency graph (as a dependency of eg. cheerio, or htmlparser2), and including it directly might not even increase your bundle size. The same is true for other entity libraries, so have a look through your node_modules directory!

Does entities support tree shaking?

Yes! Note that for best results, you should not use the encode and decode functions, as they wrap around a number of other functions, all of which will remain in the bundle. Instead, use the functions that you need directly.

Acknowledgements

This library wouldn't be possible without the work of these individuals. Thanks to

• @mathiasbynens for his explanations about character encodings, and his library he, which was one of the inspirations for entities
• @inikulin for his work on optimized tries for decoding HTML entities for the parse5 project
• @mdevils for taking on the challenge of producing a quick entity library with his html-entities library. entities would be quite a bit slower if there wasn't any competition. Right now entities is on top, but we'll see how long that lasts!

License: BSD-2-Clause

Security contact information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

Similar packages

Other packages similar to entities

he

The 'he' package is an HTML entity encoder/decoder written in JavaScript. It is robust and handles a large number of character references. It is similar to 'entities' but has a different API and additional options for encoding.

html-entities

This package is another alternative for encoding and decoding HTML entities. It provides a similar set of functionalities as 'entities' and is often used for the same purposes in different projects.