he

What is he?

The 'he' npm package is a robust HTML entity encoder/decoder written in JavaScript. It supports all standardized named character references, numeric character references, and it can encode/decode any arbitrary data in UTF-8 encoding. It is designed to work in all modern web browsers and can be used with Node.js.

What are he's main functionalities?

Encode HTML entities

This feature allows you to encode text into HTML entities, which is useful for preventing XSS attacks by sanitizing user input before inserting it into the DOM.

const he = require('he');
const encoded = he.encode('Schrödinger’s cat & Co.');
console.log(encoded); // 'Schrödinger’s cat & Co.'

Decode HTML entities

This feature allows you to decode HTML entities back into their original form, which is useful for displaying encoded content as plain text.

const he = require('he');
const decoded = he.decode('Schrödinger’s cat & Co.');
console.log(decoded); // 'Schrödinger’s cat & Co.'

Escape XML entities

This feature allows you to escape XML entities, which is similar to encoding but specifically for XML content.

const he = require('he');
const escaped = he.escape('Schrödinger’s cat & Co.');
console.log(escaped); // 'Schrödinger’s cat & Co.'

Unescape XML entities

This feature allows you to unescape XML entities, which is the reverse process of escaping and is used to convert XML-encoded content back to its original form.

const he = require('he');
const unescaped = he.unescape('Schrödinger’s cat & Co.');
console.log(unescaped); // 'Schrödinger’s cat & Co.'

Other packages similar to he

entities

Similar to 'he', 'entities' is a package for encoding and decoding HTML/XML entities. It offers a streaming interface, which 'he' does not, potentially making it more suitable for processing large amounts of data.

html-entities

This package also provides methods for encoding and decoding HTML entities. It has a slightly different API and may offer additional functions for handling named entities, which could be preferred in certain use cases over 'he'.

escape-html

While 'escape-html' is more limited in scope, focusing only on escaping strings for safe insertion into HTML content, it is a lightweight alternative to 'he' for projects that only require this specific functionality.

README

he

he (for “HTML entities”) is a robust HTML entity encoder/decoder written in JavaScript. It supports all standardized named character references as per HTML, handles ambiguous ampersands just like a browser would, has an extensive test suite, and — contrary to many other JavaScript solutions — he handles astral Unicode symbols just fine. An online demo is available.

Installation

Via npm:

npm install he

Via Bower:

bower install he

Via Component:

component install mathiasbynens/he

In a browser:

<script src="he.js"></script>

In Narwhal, Node.js, and RingoJS:

var he = require('he');

In Rhino:

load('he.js');

Using an AMD loader like RequireJS:

require(
  {
    'paths': {
      'he': 'path/to/he'
    }
  },
  ['he'],
  function(he) {
    console.log(he);
  }
);

API

he.version

A string representing the semantic version number.

he.encode(text, options)

This function takes a string of text and encodes any symbols that aren’t printable ASCII symbols and that can be replaced with named character references. For example, it would turn © into ©, but it wouldn’t turn + into + since there is no point in doing so. Additionally, it replaces any remaining non-ASCII symbols with a hexadecimal escape sequence (e.g. 𝌆).

he.encode('foo © bar ≠ baz 𝌆 qux');
// → 'foo © bar ≠ baz 𝌆 qux'

The options object is optional. It recognizes the following properties:

useNamedReferences

The default value for the useNamedReferences option is false. This means that encode() will not use any named character references (e.g. ©) in the output — hexadecimal escapes (e.g. ©) will be used instead. Set it to true to enable the use of named references.

Note that if compatibility with older browsers is a concern, this option should remain disabled.

// Using the global default setting (defaults to `false`):
he.encode('foo © bar ≠ baz 𝌆 qux');
// → 'foo © bar ≠ baz 𝌆 qux'

// Passing an `options` object to `encode`, to explicitly disallow named references:
he.encode('foo © bar ≠ baz 𝌆 qux', {
	'useNamedReferences': false
});
// → 'foo © bar ≠ baz 𝌆 qux'

// Passing an `options` object to `encode`, to explicitly allow named references:
he.encode('foo © bar ≠ baz 𝌆 qux', {
	'useNamedReferences': true
});
// → 'foo © bar ≠ baz 𝌆 qux'

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.

// Read the global default setting:
he.encode.options.useNamedReferences;
// → `false` by default

// Override the global default setting:
he.encode.options.useNamedReferences = true;

// Using the global default setting, which is now `true`:
he.encode('foo © bar ≠ baz 𝌆 qux');
// → 'foo © bar ≠ baz 𝌆 qux'

he.decode(html, options)

This function takes a string of HTML and decodes any named and numerical character references in it.

he.encode('foo © bar ≠ baz 𝌆 qux');
// → 'foo © bar ≠ baz 𝌆 qux'

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&ampbar');
// → 'foo&bar'

// Passing an `options` object to `decode`, to explicitly assume an HTML text context:
he.encode('foo&ampbar', {
  'isAttributeValue': false
});
// → 'foo&bar'

// Passing an `options` object to `encode`, to explicitly assume an HTML attribute value context:
he.encode('foo&ampbar', {
  'isAttributeValue': true
});
// → 'foo&ampbar'

The global default setting 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 the 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&ampbar');
// → 'foo&ampbar'

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 \.

he.escape('<img src=\'x\' onerror="prompt(1)">');
// → '&lt;img src=&#x27;x&#x27; onerror=&quot;prompt(1)&quot;&gt;'

he.unescape(html)

he.unescape is an alias for he.decode. It takes a string of HTML and decodes any named and numerical character references in it.

Support

he has been tested in at least Chrome 27-29, Firefox 3-22, Safari 4-6, Opera 10-12, IE 6-10, Node.js v0.10.0, Narwhal 0.3.2, RingoJS 0.8-0.9, PhantomJS 1.9.0, and Rhino 1.7RC4.

Unit tests & code coverage

After cloning this repository, run npm install to install the dependencies needed for he development and testing. You may want to install Istanbul globally using npm install istanbul -g.

Once that’s done, you can run the unit tests in Node using npm test or node tests/tests.js. To run the tests in Rhino, Ringo, Narwhal, and web browsers as well, use grunt test.

To generate the code coverage report, use grunt cover.

Acknowledgements

Thanks to Simon Pieters (@zcorpan) for the many suggestions.

Author

Mathias Bynens

License

he is available under the MIT license.