Handling HTML Entities and Sanitization: entities vs he vs html-entities vs sanitize-html

When working with HTML strings in JavaScript — whether rendering user content, parsing RSS feeds, or building static site generators — you’ll inevitably face two related but distinct problems: (1) correctly converting between raw characters and their escaped HTML entity forms (e.g., & ↔ &), and (2) safely displaying untrusted HTML without exposing your app to XSS attacks. The packages entities, he, html-entities, and sanitize-html all touch this space, but they solve different layers of the problem. Let’s break down what each does, how they work, and when to use which.

🔤 Core Functionality: What Each Package Actually Does

entities: Low-Level, Spec-Aware Entity Conversion

entities is a minimal, zero-dependency library built for speed and correctness in entity encoding and decoding. It doesn’t pretend to be a sanitizer — it only handles the conversion between plain text and HTML/XML entities. It supports both named (©) and numeric (©) references and lets you choose decoding modes (strict, loose, etc.).

// Using entities
import { encode, decode } from 'entities';

const encoded = encode('AT&T > 5 & < 10');
// Result: 'AT&amp;T &gt; 5 &amp; &lt; 10'

const decoded = decode('&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;');
// Result: '<script>alert("xss")</script>'

Note: This does not remove the <script> tag — it only decodes entities. That’s intentional.

he: HTML5-Compliant Entity Handling

he (short for “HTML Entities”) strictly implements the HTML5 specification for entity parsing. It’s battle-tested and used in projects like Markdown parsers where spec compliance matters. Like entities, it only encodes/decodes — no sanitization.

// Using he
import { encode, decode } from 'he';

const encoded = encode('foo © bar ≠ baz 𝌆 qux');
// Result: 'foo © bar ≠ baz 𝌆 qux'

const decoded = decode('<img src=x onerror=alert(1)>');
// Result: '<img src=x onerror=alert(1)>'

Again, dangerous HTML remains intact — he assumes you’ll handle security separately.

html-entities: Class-Based API with Multiple Standards

html-entities takes a more object-oriented approach. You instantiate encoders/decoders for specific standards (HTML4, HTML5, XML), which is handy if your app deals with mixed document types.

// Using html-entities
import { Html5Entities } from 'html-entities';

const entities = new Html5Entities();

const encoded = entities.encode('5 > 3 & 2 < 4');
// Result: '5 &gt; 3 &amp; 2 &lt; 4'

const decoded = entities.decode('&lt;div onclick="steal()"&gt;Click me&lt;/div&gt;');
// Result: '<div onclick="steal()">Click me</div>'

The class-based design allows reuse with consistent settings, but adds slight overhead compared to function-based alternatives.

sanitize-html: Security-First HTML Cleaning

sanitize-html is in a different category. Its job isn’t just decoding — it’s removing unsafe HTML to prevent XSS. It parses the input into a DOM-like structure, walks the tree, and strips disallowed tags/attributes based on a configurable allowlist.

// Using sanitize-html
import sanitizeHtml from 'sanitize-html';

const dirty = '<script>alert("xss")</script><p>Hello <b>world</b>!</p>';
const clean = sanitizeHtml(dirty);
// Result: '<p>Hello <b>world</b>!</p>'

// It also decodes entities during parsing
const withEntities = '&lt;img src=x onerror=alert(1)&gt;';
const cleaned = sanitizeHtml(withEntities);
// Result: '' (empty string — no valid tags after decoding)

Crucially, sanitize-html always decodes entities as part of parsing, so you never see raw < in the output — only the actual < character, which is then evaluated for safety.

⚖️ Key Trade-Offs: Performance, Safety, and Scope

When You Only Need Encoding/Decoding

If your task is purely transforming text ↔ entities (e.g., preparing strings for HTML insertion or parsing API responses that return escaped HTML), do not use sanitize-html. It’s overkill: it parses full HTML, walks a DOM tree, and applies rules — all unnecessary overhead.

Between entities, he, and html-entities:

• entities is fastest and smallest. Use it in performance-sensitive contexts (e.g., SSR at scale).
• he is best when you must match browser behavior exactly (e.g., in a Markdown-to-HTML pipeline).
• html-entities shines when you need to switch between XML/HTML4/HTML5 modes or reuse configured instances.

When You Must Prevent XSS

If you’re rendering user-provided HTML (from a CMS, comment box, or WYSIWYG editor), only sanitize-html is appropriate. The others will happily give you executable script tags if the input contains them — even after decoding.

Example of why this matters:

// ❌ Dangerous: using a decoder alone
const userInput = '<script>stealCookies()</script>';
const decoded = decode(userInput); // from any of the first three libs
// decoded = '<script>stealCookies()</script>'
document.body.innerHTML = decoded; // 💥 XSS vulnerability!

// ✅ Safe: using sanitize-html
const clean = sanitizeHtml(userInput);
// clean = '' (script tag removed)
document.body.innerHTML = clean; // safe

sanitize-html also supports advanced features like:

• Custom allowed tags/attributes
• Transform functions (e.g., add rel="noopener" to links)
• Disabling entity decoding (though rarely needed)

🧪 Real-World Usage Scenarios

Scenario 1: Rendering API Data with Escaped HTML

You fetch blog posts from a REST API that returns titles like "Why 5 > 3 Matters". You just need to display the real characters.

✅ Best choice: entities or he

// Simple decoding
const title = decode(apiResponse.title); // "Why 5 > 3 Matters"

No sanitization needed — the data is trusted.

Scenario 2: Building a Static Site Generator

Your SSG processes Markdown files that may contain inline HTML. You need to encode code snippets for HTML output but also ensure user-authored HTML doesn’t break layout or introduce scripts.

✅ Best combo: Use entities for encoding code blocks + sanitize-html for final output.

// Encode special chars in code
const codeHtml = `<code>${encode(codeString)}</code>`;

// Later, sanitize full page HTML
const finalHtml = sanitizeHtml(pageWithUserHtml);

Scenario 3: Accepting Rich Text from Users

Your app has a rich text editor (e.g., TinyMCE) that outputs HTML like <p>Hello <strong>you</strong></p>. You must store and later render this safely.

✅ Only choice: sanitize-html

const cleanHtml = sanitizeHtml(userHtml, {
  allowedTags: ['p', 'strong', 'em', 'a'],
  allowedAttributes: { 'a': ['href'] }
});

Never decode first — let sanitize-html handle parsing and cleaning in one secure step.

📋 Summary Table

💡 Final Guidance

• Never mix concerns: Don’t use sanitizers for simple encoding, and don’t use decoders when you need security.
• Trust your data source: If HTML comes from your own backend (not users), decoding alone is fine. If it’s user-generated, always sanitize.
• Combine when needed: In complex apps (e.g., SSGs), you might use entities for intermediate encoding and sanitize-html for final output.

Remember: entity decoding and HTML sanitization are related but separate responsibilities. Choose the right tool for the job — your app’s security and performance depend on it.