# unescape-unicode

> Library to unescape Unicode characters

Latest version **0.3.0** (published 2025-08-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install unescape-unicode
pnpm add unescape-unicode
yarn add unescape-unicode
bun add unescape-unicode
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2025-08-04 |
| First published | 2018-01-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 121.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | neocotic |
| Maintainers | neocotic |
| Keywords | converter, unicode, unescape |

## Links

- npm: https://www.npmjs.com/package/unescape-unicode
- Repository: https://github.com/neocotic/unescape-unicode
- Issues: https://github.com/neocotic/unescape-unicode/issues
- Funding: https://github.com/sponsors/neocotic
- npm.io page: https://npm.io/package/unescape-unicode

## Recent versions

- 0.3.0 (latest) — 2025-08-04
- 0.2.0 — 2018-11-09
- 0.1.0 — 2018-01-25

## README

# unescape-unicode

[![Build Status](https://img.shields.io/github/actions/workflow/status/neocotic/unescape-unicode/ci.yml?event=push&style=for-the-badge)](https://github.com/neocotic/unescape-unicode/actions/workflows/ci.yml)
[![Downloads](https://img.shields.io/npm/dw/unescape-unicode?style=for-the-badge)](https://github.com/neocotic/unescape-unicode)
[![Release](https://img.shields.io/npm/v/unescape-unicode?style=for-the-badge)](https://github.com/neocotic/unescape-unicode)
[![License](https://img.shields.io/github/license/neocotic/unescape-unicode?style=for-the-badge)](https://github.com/neocotic/unescape-unicode/blob/main/LICENSE.md)

[unescape-unicode](https://github.com/neocotic/unescape-unicode) is a [Node.js](https://nodejs.org) package for
converting Unicode escapes ("\uxxxx" notation) into their corresponding Unicode characters.

## Install

Install using [npm](https://npmjs.com):

``` sh
npm install --save unescape-unicode
```

## Usage

### `unescapeUnicode(input[, options])`

Converts Unicode escapes within `input` to their corresponding characters.

Characters that are not part of Unicode escapes are included in the returned string as-is. This includes invalid or
incomplete Unicode escapes (e.g. `\uxxxx`) and any other unrelated escape sequences (e.g. `\t`). This can be controlled
by specifying the `replacer` option.

Characters within the Basic Multilingual Plane (BMP) as well as surrogate pairs for characters outside BMP are
supported.

#### Options

| Option     | Type       | Default | Description                                                                                                                           |
|------------|------------|---------|---------------------------------------------------------------------------------------------------------------------------------------|
| `replacer` | `Replacer` | *None*  | A function that returns a replacement string for an individual escape character represented by a specific Unicode code point, if any. |

#### Examples

``` javascript
import { replaceChars, unescapeUnicode } from "unescape-unicode";

unescapeUnicode("I \\u2665 Unicode!");
//=> "I ♥ Unicode!"
unescapeUnicode("I\\t\\u2665\tUnicode!", { replacer: replaceChars({ f: "\f", n: "\n", r: "\r", t: "\t" }) });
//=> "I	♥	Unicode!"
unescapeUnicode("\\ud842\\udfb7\\ud842\\udfbe");
//=> "𠮷𠮾"
```

### `Replacer(code, char)`

A function that returns a replacement string for an individual escape character (i.e. the character immediately
following a backslash character) represented by the specified Unicode code point, if any.

If an empty string is returned, the escape sequence will be removed from the returned string. If either `null` or
`undefined` are returned, the escape sequence will be included in the returned string as-is.

This function is only passed `u` if not part of a valid Unicode escape sequence.

There are a several built-in `Replacer` functions provided.

#### `composeReplacer(...replacers)`

Returns a `Replacer` composed of the specified `replacers` that returns the replacement string returned from the first
`Replacer` to return a string, where possible.

``` javascript
import { composeReplacer, replaceChars, replaceUnescaped, unescapeUnicode } from "unescape-unicode";

const replacer = composeReplacer(
  replaceChars({ f: "\f", n: "\n", r: "\r", t: "\t" }),
  replaceUnescaped(),
);
unescapeUnicode("I\\t\\u2665\\tUnicode\\\\!", { replacer });
//=> "I	♥	Unicode\\!"
```

#### `replaceConstant(replacement)`

Returns a `Replacer` that always returns the specified `replacement`.

``` javascript
import { replaceConstant, unescapeUnicode } from "unescape-unicode";

unescapeUnicode("I\\t\\u2665\\tUnicode!", { replacer: replaceConstant("?") });
//=> "I?♥?Unicode!"
```

#### `replaceChar(char, replacement)`

Returns a `Replacer` that returns the specified `replacement` string for the individual escape character (i.e. the
character immediately following a backslash character) provided.

``` javascript
import { replaceChar, unescapeUnicode } from "unescape-unicode";

unescapeUnicode("I\\t\\u2665\\tUnicode!", { replacer: replaceChar("t", "\t") });
//=> "I	♥	Unicode!"
```

#### `replaceChars(replacements)`

Returns a `Replacer` that returns replacement strings looked up from the specified `replacements`, where possible.

The keys within `replacements` are expected to be the individual escape characters (i.e. the character immediately
following a backslash character). It can either be provided as a `Map` or an object.

``` javascript
import { replaceChars, unescapeUnicode } from "unescape-unicode";

const replacements = {
  f: "\f",
  n: "\n",
  r: "\r",
  t: "\t",
};
unescapeUnicode("I\\t\\u2665\\tUnicode!", { replacer: replaceChars(replacements) });
//=> "I	♥	Unicode!"
```

#### `replaceCode(code, replacement)`

Returns a `Replacer` that returns the specified `replacement` string for the Unicode code point representing the
individual escape character (i.e. the character immediately following a backslash character) provided.

``` javascript
import { replaceCode, unescapeUnicode } from "unescape-unicode";

unescapeUnicode("I\\t\\u2665\\tUnicode!", { replacer: replaceCode(0x0074, "\t") });
//=> "I	♥	Unicode!"
```

#### `replaceCodes(replacements)`

Returns a `Replacer` that returns replacement strings looked up from the specified `replacements`, where possible.

The keys within `replacements` are expected to be Unicode code points representing the individual escape characters
(i.e. the character immediately following a backslash character). It can either be provided as a `Map` or an object.

``` javascript
import { replaceCodes, unescapeUnicode } from "unescape-unicode";

const replacements = new Map([
  [0x0066, "\f"],
  [0x006e, "\n"],
  [0x0072, "\r"],
  [0x0074, "\t"],
]);
unescapeUnicode("I\\t\\u2665\\tUnicode!", { replacer: replaceCodes(replacements) });
//=> "I	♥	Unicode!"
```

#### `replaceUnescaped()`

Returns a `Replacer` that always returns the individual escape character (i.e. the character immediately following a
backslash character) as the replacement string.

``` javascript
import { replaceUnescaped, unescapeUnicode } from "unescape-unicode";

unescapeUnicode("I\\t\\u2665\\tUnicode!", { replacer: replaceUnescaped() });
//=> "It♥tUnicode!"
```

## Related

* [escape-unicode](https://github.com/neocotic/escape-unicode)
* [node-native2ascii](https://github.com/neocotic/node-native2ascii)
* [properties-store](https://github.com/neocotic/properties-store)

## Bugs

If you have any problems with this package or would like to see changes currently in development, you can do so
[here](https://github.com/neocotic/unescape-unicode/issues).

## Contributors

If you want to contribute, you're a legend! Information on how you can do so can be found in
[CONTRIBUTING.md](https://github.com/neocotic/unescape-unicode/blob/main/CONTRIBUTING.md). We want your suggestions and
pull requests!

A list of all contributors can be found in
[AUTHORS.md](https://github.com/neocotic/unescape-unicode/blob/main/AUTHORS.md).

## License

Copyright © 2025 neocotic

See [LICENSE.md](https://github.com/neocotic/unescape-unicode/raw/main/LICENSE.md) for more information on our MIT
license.

---
_Source: https://npm.io/package/unescape-unicode · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._