152 lines
7.6 KiB
Markdown
152 lines
7.6 KiB
Markdown
# entities [](https://npmjs.org/package/entities) [](https://npmjs.org/package/entities) [](https://github.com/fb55/entities/actions/workflows/nodejs-test.yml)
|
||
|
||
Encode & decode HTML & XML entities with ease & speed.
|
||
|
||
## Features
|
||
|
||
- 😇 Tried and true: `entities` is used by many popular libraries; eg.
|
||
[`htmlparser2`](https://github.com/fb55/htmlparser2), the official
|
||
[AWS SDK](https://github.com/aws/aws-sdk-js-v3) and
|
||
[`commonmark`](https://github.com/commonmark/commonmark.js) use it to process
|
||
HTML entities.
|
||
- ⚡️ Fast: `entities` is the fastest library for decoding HTML entities (as of
|
||
September 2025); see [performance](#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`
|
||
|
||
```javascript
|
||
import * as entities from "entities";
|
||
|
||
// Encoding
|
||
entities.escapeUTF8("& ü"); // "& ü"
|
||
entities.encodeXML("& ü"); // "& ü"
|
||
entities.encodeHTML("& ü"); // "& ü"
|
||
|
||
// Decoding
|
||
entities.decodeXML("asdf & ÿ ü '"); // "asdf & ÿ ü '"
|
||
entities.decodeHTML("asdf & ÿ ü '"); // "asdf & ÿ ü '"
|
||
```
|
||
|
||
## Performance
|
||
|
||
Benchmarked in October 2026 with Node v26.9.0 on AMD Ryzen 7 5800X3D
|
||
(median of three runs). Other libraries are shown relative to `entities`.
|
||
|
||
### Decoding
|
||
|
||
| Library | Short text (49 B) | Plain prose (4.0 KiB) | Prose with references (4.0 KiB) | All named references (19.9 KiB) | Numeric references (4.0 KiB) |
|
||
| -------------------- | ----------------: | --------------------: | ------------------------------: | ------------------------------: | ---------------------------: |
|
||
| entities | 578 MB/s | 131,381 MB/s | 1,425 MB/s | 161 MB/s | 272 MB/s |
|
||
| html-entities 2.6.0 | 5.5× slower | 61× slower | 4.8× slower | 2.7× slower | 7.1× slower |
|
||
| he 2.0.0 | 7.8× slower | 61× slower | 7.5× slower | 5.0× slower | 8.0× slower |
|
||
| parse-entities 4.0.2 | 14× slower | 1,040× slower | 30× slower | 13× slower | 5.0× slower |
|
||
| ent 2.2.2 | 10× slower | 61× slower | 10× slower | 6.9× slower | 11× slower |
|
||
|
||
`entities` returns input without `&` after a single `indexOf` scan, hence
|
||
the plain prose result.
|
||
|
||
### Encoding
|
||
|
||
| Library | Short text (48 B) | ASCII prose (4.0 KiB) | Accented prose (4.0 KiB) | CJK and emoji (4.0 KiB) |
|
||
| ------------------------ | ----------------: | --------------------: | -----------------------: | ----------------------: |
|
||
| entities | 195 MB/s | 1,107 MB/s | 251 MB/s | 127 MB/s |
|
||
| html-entities 2.6.0 | 3.0× slower | 1.1× slower | 1.6× slower | 2.7× slower |
|
||
| he 2.0.0 | 9.4× slower | 2.0× slower | 4.3× slower | 4.4× slower |
|
||
| stringify-entities 4.0.4 | 8.0× slower | 1.7× slower | 3.8× slower | 5.6× slower |
|
||
| ent 2.2.2 | 14× slower | 98× slower | 23× slower | 5.3× slower |
|
||
|
||
### Escaping
|
||
|
||
| Library | Short text (48 B) | Prose (4.0 KiB) | Markup (4.1 KiB) |
|
||
| ------------------------ | ----------------: | --------------: | ---------------: |
|
||
| entities | 326 MB/s | 4,447 MB/s | 304 MB/s |
|
||
| html-entities 2.6.0 | 2.3× slower | 1.8× slower | 1.7× slower |
|
||
| he 2.0.0 | 2.1× slower | 1.7× slower | 1.6× slower |
|
||
| stringify-entities 4.0.4 | 3.6× slower | 2.7× slower | 2.8× slower |
|
||
| html-escaper 3.0.3 | 2.2× slower | 1.7× slower | 1.6× slower |
|
||
| lodash 4.18.1 | 2.4× slower | 1.8× slower | 1.7× slower |
|
||
|
||
### Unescaping
|
||
|
||
| Library | Short text (62 B) | Prose (4.1 KiB) | Markup (5.7 KiB) |
|
||
| -------------------- | ----------------: | --------------: | ---------------: |
|
||
| entities | 329 MB/s | 4,552 MB/s | 410 MB/s |
|
||
| html-entities 2.6.0 | 3.7× slower | 5.7× slower | 3.7× slower |
|
||
| he 2.0.0 | 5.2× slower | 8.4× slower | 5.8× slower |
|
||
| parse-entities 4.0.2 | 8.0× slower | 75× slower | 13× slower |
|
||
| ent 2.2.2 | 7.8× slower | 11× slower | 8.9× slower |
|
||
| html-escaper 3.0.3 | 2.8× slower | 5.2× slower | 3.0× slower |
|
||
| lodash 4.18.1 | 3.0× slower | 4.8× slower | 3.0× slower |
|
||
|
||
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 October 2026, `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](https://github.com/mathiasbynens) for his explanations about
|
||
character encodings, and his library `he`, which was one of the inspirations
|
||
for `entities`
|
||
- [@inikulin](https://github.com/inikulin) for his work on optimized tries for
|
||
decoding HTML entities for the `parse5` project
|
||
- [@mdevils](https://github.com/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](https://tidelift.com/security). Tidelift will
|
||
coordinate the fix and disclosure.
|