HTML Entity Handling in JavaScript: entities vs he vs html-entities

When you’re building web apps, you often need to convert special characters into safe HTML entities (like turning <script> into <script>) or decode them back for display. The three main libraries for this in the JavaScript ecosystem are entities, he, and html-entities. They all solve the same core problem but with different design philosophies, APIs, and trade-offs. Let’s compare them head-to-head.

🔤 Basic Encoding and Decoding

All three packages support encoding (converting characters to entities) and decoding (converting entities back to characters), but their function signatures differ.

entities uses simple top-level functions:

import { encode, decode } from 'entities';

const encoded = encode('<div>Hello & "world"</div>');
// '&lt;div&gt;Hello &amp; &quot;world&quot;&lt;/div&gt;'

const decoded = decode('&lt;div&gt;Hello &amp; &quot;world&quot;&lt;/div&gt;');
// '<div>Hello & "world"</div>'

he also provides straightforward functions:

import * as he from 'he';

const encoded = he.encode('<div>Hello & "world"</div>');
// '&lt;div&gt;Hello &amp; &quot;world&quot;&lt;/div&gt;'

const decoded = he.decode('&lt;div&gt;Hello &amp; &quot;world&quot;&lt;/div&gt;');
// '<div>Hello & "world"</div>'

html-entities requires creating an instance first:

import { Html5Entities } from 'html-entities';

const entities = new Html5Entities();

const encoded = entities.encode('<div>Hello & "world"</div>');
// '&lt;div&gt;Hello &amp; &quot;world&quot;&lt;/div&gt;'

const decoded = entities.decode('&lt;div&gt;Hello &amp; &quot;world&quot;&lt;/div&gt;');
// '<div>Hello & "world"</div>'

💡 Note: html-entities offers separate classes like XmlEntities, Html4Entities, and Html5Entities, while entities and he handle standards via options or built-in logic.

⚙️ Configuration and Control

How much control do you have over what gets encoded or decoded?

entities gives you granular control through options:

import { encode } from 'entities';

// Only encode non-ASCII characters
encode('café', { level: 'nonAscii' });
// 'café'

// Use XML-compatible encoding (no named entities)
encode('< &', { mode: 'xml' });
// '&lt; &amp;'

he focuses on strict HTML5 compliance but allows some decoding tweaks:

import * as he from 'he';

// Decode with strict mode (disallow ambiguous ampersands)
he.decode('AT&T', { strict: true });
// Throws error — 'AT&T' isn't a valid entity

// Default is lenient
he.decode('AT&T');
// 'AT&T'

html-entities lets you configure behavior at instantiation:

import { Html5Entities } from 'html-entities';

const entities = new Html5Entities({
  level: 'all', // or 'basic', 'nonAscii'
  encodeOptions: {
    useNamedReferences: false,
    decimal: true,
    hexadecimal: false
  }
});

entities.encode('©');
// '©' instead of '©'

This makes html-entities well-suited for scenarios where you reuse the same settings repeatedly—like in a server-rendered template engine.

📏 Supported Character Sets and Standards

Each library handles different sets of named entities:

• entities supports XML, HTML4, and HTML5 via the mode option ('xml', 'html4', 'html5'). By default, it uses HTML5.
• he strictly implements the HTML5 spec, including obscure and legacy entities. It’s known for its completeness and correctness.
• html-entities provides distinct classes: XmlEntities (only <, >, etc.), Html4Entities, and Html5Entities, each with their own dictionary.

For example, the euro symbol €:

// entities (default = HTML5)
encode('€'); // '€'

// he
he.encode('€'); // '€'

// html-entities (Html5Entities)
new Html5Entities().encode('€'); // '€'

But if you use XmlEntities from html-entities, it won’t use € (since XML doesn’t define it) and will fall back to numeric form if allowed.

🚀 Performance and Use Case Fit

• entities is optimized for speed and small bundle size. It’s used internally by popular libraries like parse5 and cheerio. If you’re building a high-throughput SSR service or a static site generator, this is likely your best bet.
• he prioritizes spec compliance over raw speed. It’s slower than entities but more accurate in edge cases involving ambiguous or malformed entities. Great for parsers, validators, or data cleanup tools.
• html-entities trades a bit of performance for API flexibility. The class-based approach adds slight overhead but pays off when you need reusable, pre-configured encoders/decoders.

🛑 Error Handling and Edge Cases

How do they behave with malformed input?

• entities decodes invalid entities as-is. decode('&xyz;') returns '&xyz;'.
• he does the same by default but can be set to strict mode to throw on invalid entities.
• html-entities always leaves unknown entities untouched—decode('&xyz;') → '&xyz;'.

None of them attempt to “fix” broken markup beyond entity handling, which is correct behavior.

🌐 Browser and Node.js Support

All three work in both environments. None rely on DOM APIs, so they run cleanly in Node.js, Web Workers, or edge runtimes like Cloudflare Workers.

✅ Summary Table

💡 Final Recommendation

• Need speed and simplicity in a modern app? Go with entities.
• Building a parser or validator that must follow HTML5 to the letter? Choose he.
• Creating a templating system or editor where you’ll reuse the same encoding rules? html-entities’s instance-based API will feel natural.

All three are actively maintained and production-ready—so your choice should hinge on your project’s architectural needs, not fear of obsolescence.