_he_(for“HTMLentities”)isarobustHTMLentityencoder/decoderwritteninJavaScript.Itsupports[allstandardizednamedcharacterreferencesasperHTML](https://html.spec.whatwg.org/multipage/syntax.html#named-character-references), handles [ambiguous ampersands](https://mathiasbynens.be/notes/ambiguous-ampersands) and other edge cases [just like a browser would](https://html.spec.whatwg.org/multipage/syntax.html#tokenizing-character-references), has an extensive test suite, and — contrary to many other JavaScript solutions — _he_ handles astral Unicode symbols just fine. [An online demo is available.](https://mothereff.in/html-entities)
Aslongastheinputstringcontains[allowedcodepoints](https://html.spec.whatwg.org/multipage/parsing.html#preprocessing-the-input-stream) only, the return value of this function is always valid HTML. Any [(invalid) code points that cannot be represented using a character reference](https://html.spec.whatwg.org/multipage/syntax.html#table-charref-overrides) in the input are not encoded:
```js
he.encode('foo\0bar');
// → 'foo \0 bar'
```
However,enabling[the`strict` option](https://github.com/mathiasbynens/he#strict) causes invalid code points to throw an exception. With `strict` enabled, `he.encode`eitherthrows(iftheinputcontainsinvalidcodepoints)orreturnsastringofvalidHTML.
Thedefaultvalueforthe`encodeEverything` option is `false`. This means that `encode()` will not use any character references for printable ASCII symbols that don’t need escaping. Set it to `true` to encode every symbol in the input string. When set to `true`, this option takes precedence over `allowUnsafeSymbols` (i.e. setting the latter to `true`insuchacasehasnoeffect).
```js
// Using the global default setting (defaults to `false`):
Thedefaultvalueforthe`strict` option is `false`. This means that `encode()` will encode any HTML text content you feed it, even if it contains any symbols that cause [parse errors](https://html.spec.whatwg.org/multipage/parsing.html#preprocessing-the-input-stream). To throw an error when such invalid HTML is encountered, set the `strict` option to `true`.Thisoptionmakesitpossibletouse_he_aspartofHTMLparsersandHTMLvalidators.
```js
// Using the global default setting (defaults to `false`, i.e. error-tolerant mode):
he.encode('\x01');
// → ''
// Passing an `options` object to `encode`, to explicitly enable error-tolerant mode:
he.encode('\x01',{
'strict':false
});
// → ''
// Passing an `options` object to `encode`, to explicitly enable strict mode:
he.encode('\x01',{
'strict':true
});
// → Parse error
```
####`allowUnsafeSymbols`
Thedefaultvalueforthe`allowUnsafeSymbols` option is `false`. This means that characters that are unsafe for use in HTML content (`&`, `<`, `>`, `"`, `'`, and `` ` ``) will be encoded. When set to `true`, only non-ASCII characters will be encoded. If the `encodeEverything` option is set to `true`,thisoptionwillbeignored.
Theglobaldefaultsettingcanbeoverriddenbymodifyingthe`he.encode.options` object. This saves you from passing in an `options` object for every call to `encode`ifyouwanttousethenon-defaultsetting.
```js
// 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`:
Thedefaultvalueforthe`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](https://html.spec.whatwg.org/multipage/syntax.html#data-state). HTML has different rules for [parsing character references in attribute values](https://html.spec.whatwg.org/multipage/syntax.html#character-reference-in-attribute-value-state) — set this option to `true`totreattheinputstringasifitwereusedasanattributevalue.
```js
// Using the global default setting (defaults to `false`, i.e. HTML text context):
he.decode('foo&bar');
// → 'foo&bar'
// Passing an `options` object to `decode`, to explicitly assume an HTML text context:
he.decode('foo&bar',{
'isAttributeValue':false
});
// → 'foo&bar'
// Passing an `options` object to `decode`, to explicitly assume an HTML attribute value context:
he.decode('foo&bar',{
'isAttributeValue':true
});
// → 'foo&bar'
```
####`strict`
Thedefaultvalueforthe`strict` option is `false`. This means that `decode()` will decode any HTML text content you feed it, even if it contains any entities that cause [parse errors](https://html.spec.whatwg.org/multipage/syntax.html#tokenizing-character-references). To throw an error when such invalid HTML is encountered, set the `strict` option to `true`.Thisoptionmakesitpossibletouse_he_aspartofHTMLparsersandHTMLvalidators.
```js
// Using the global default setting (defaults to `false`, i.e. error-tolerant mode):
he.decode('foo&bar');
// → 'foo&bar'
// Passing an `options` object to `decode`, to explicitly enable error-tolerant mode:
he.decode('foo&bar',{
'strict':false
});
// → 'foo&bar'
// Passing an `options` object to `decode`, to explicitly enable strict mode:
he.decode('foo&bar',{
'strict':true
});
// → Parse error
```
####Overridingdefault`decode`optionsglobally
Theglobaldefaultsettingsforthe`decode` function can be overridden by modifying the `he.decode.options` object. This saves you from passing in an `options` object for every call to `decode`ifyouwanttouseanon-defaultsetting.
```js
// 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&bar');
// → 'foo&bar'
```
###`he.escape(text)`
ThisfunctiontakesastringoftextandescapesitforuseintextcontextsinXMLorHTMLdocuments.Onlythefollowingcharactersareescaped:`&`, `<`, `>`, `"`, `'`, and `` ` ``.
Aftercloningthisrepository,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`.
Oncethat’sdone,youcanruntheunittestsinNodeusing`npm test` or `node tests/tests.js`. To run the tests in Rhino, Ringo, Narwhal, and web browsers as well, use `grunt test`.
Togeneratethecodecoveragereport,use`grunt cover`.
##Acknowledgements
Thanksto[SimonPieters](https://simon.html5.org/) ([@zcorpan](https://twitter.com/zcorpan)) for the many suggestions.
##Author
|[](https://twitter.com/mathias "Follow @mathias on Twitter") |