# @hackmd/emojify.js

> A Javascript module to convert emoji keywords to images.

Latest version **3.0.2** (published 2025-06-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @hackmd/emojify.js
pnpm add @hackmd/emojify.js
yarn add @hackmd/emojify.js
bun add @hackmd/emojify.js
```

## Health

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

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

Warnings: low downloads; no esm support; large bundle.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.2 |
| Published | 2025-06-24 |
| First published | 2019-09-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 22.5 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | HackMD Team |
| Maintainers | a60814billy, yukaii, jackycute |
| Keywords | emoji, emojify, javascript |

## Links

- npm: https://www.npmjs.com/package/@hackmd/emojify.js
- Repository: https://github.com/hackmdio/emojify.js
- Homepage: https://github.com/hackmdio/emojify.js#readme
- Issues: https://github.com/hackmdio/emojify.js/issues
- npm.io page: https://npm.io/package/@hackmd/emojify.js

## Recent versions

- 3.0.2 (latest) — 2025-06-24
- 3.0.0 — 2025-03-12
- 2.1.0 — 2019-09-07

## README

# emojify.js

Note: This fork is a rewrite version from joypixels/emojify.js with TypeScript and up-to-date dependencies.

Below is the original README

---

A swiss-army-knife for all emoji, in Javascript. Used by [Gitter](https://gitter.im/) and [Mapbox](https://www.mapbox.com/blog/emoji-map-markers/).

The emoji keywords are as described by [emoji-cheat-sheet.com](http://www.emoji-cheat-sheet.com).

## Features

- Fast
- Awesome
- Converts emoticons like `:) :( :'(`
- Allows customisation of processed emoji
- Multiple modes; `img`, sprites and data-URI
- Available on a CDN **(gasp)**
- Includes a [sample `.htaccess` file](.htaccess) for caching Javascript and CSS
- Switchable emoji sets **(SOON!)**
- Made from unicorn blood

## Installation

### Via npm

`npm install @hackmd/emojify.js --save`

## API

### setConfig([object])

*This works in the browser and on Node*

#### Parameters

- `object` - Optional JSON object with any of the following attributes:

Option | Default | Description
--- | --- | ---
`blacklist.elements` | `['script', 'textarea', 'a', 'pre', 'code']` | An array of elements you don't want emojified
`blacklist.classes` | `['no-emojify']` | An array of classes you don't want emojified
`mode` | `img` | By default, emojify will output an `img` with a `src` attribute for each emoji found. But if `mode` is set to `sprite` or `data-uri`, then `span`s with classes are outputted. Don't forget to include the appropriate CSS for your choice though, see the `/dist` directory.
`tag_type` | `null` | When set, emojify uses this element with the class `emoji emoji-#{emojiname}` instead of an `img` with a `src` attribute.  Example valid values: `div`, `span`. This takes precedence over the `mode` option. Note: if you're not using `img`s, `.emoji-+1` isn't a valid class, so `.emoji-plus1` is used instead.
`only_crawl_id` | `null` | **[DEPRECATED]** Restricts searching for emojis to a specified element & it's children. If null, and no object is passed to `run()`, `document.body` is used
`img_dir` | `'images/emoji'` | Defines the path to the emoji images
`ignore_emoticons` | `false` | If `true`, only convert emoji like `:smile:` and ignore emoticons like `:)`

#### Usage
```js
emojify.setConfig({tag_type : 'div'});
```

---

### run([element], [replacer])

*This works in the browser and Node*

#### Parameters
- `element` - Optional HTML element to restrict the emojification to.
- `replacer` - Optional Function to override emoji replacement behaviour with your own. The function will receive two arguments, the emoji pattern found (`emoji`), and the emoji name (`name`). In the case of emoticons, for example, `emoji = ':)'` and `name = 'smile'`. Your function must return a HTMLElement.

##### Browser

```js
emojify.run();
// OR
emojify.run(document.getElementById('my-element'))
// OR
emojify.run(null, function(emoji, emojiName){
  var span = document.createElement('span');
  span.className = 'emoji emoji-'  + emojiName;
  span.innerHTML = emoji + ' replaced';
  return span;
});
```

##### Node.js

Requires you to have jsdom installed:
`npm i jsdom --save`

```js
var jsdom = require('jsdom')

jsdom.env({
    html: "<p><code>jhhh</code><em>:)</em></p>",
    done: function(errors, window) {
        emojify.run(window.document.body)
    }
});
```

---

### replace(string, [callback])

*This works in the browser and on Node*

#### Parameters

- `string` - String to emojify
- `callback` - Optional callback function to output emoji with

#### Usage

By default, emojify.js uses the internal function `defaultReplacer()` to replace emoji. You can override this behaviour by supplying your own callback function.

Your callback function will receive two arguments, the emoji pattern found (`emoji`), and the emoji name (`name`). In the case of emoticons, for example, `emoji = ':)'` and `name = 'smile'`.

The context in which your replacer function is run will have the config available. So you can access properties such as `img_dir` at `this.config.img_dir`.

```js
emojify.replace('I am happy :)');
// OR
replacer = function(emoji, name) {
    // Customise output here
    return emojifiedString;
}

emojify.replace('I am happy :)', replacer);
```

## Contributing changes

Please read [CONTRIBUTING.md](CONTRIBUTING.md).

## Credits

- [All Contributors](https://github.com/hassankhan/emojify.js/contributors)
- [Hassan Khan](https://github.com/hassankhan)
- [Yukai Huang](https://github.com/Yukaii)

## License

Please read [LICENSE.md](LICENSE.md). For image attributions, please read [LICENSE-IMAGES.md](LICENSE-IMAGES.md)

[travis]: https://travis-ci.org/hassankhan/emojify.js
[appveyor]: https://ci.appveyor.com/project/hassankhan/emojify-js
[package-bower]: http://bower.io/search/?q=emojify.js
[package-npm]: https://www.npmjs.org/package/emojify.js
[ico-build]: http://img.shields.io/travis/hassankhan/emojify.js.svg?style=flat-square
[ico-build-dev]: http://img.shields.io/travis/hassankhan/emojify.js/develop.svg?style=flat-square
[ico-windows-build]: https://ci.appveyor.com/api/projects/status/908bymld8nm3ykxm?svg=true
[ico-windows-build-dev]: https://ci.appveyor.com/api/projects/status/908bymld8nm3ykxm/branch/develop?svg=true
[ico-bower]: http://img.shields.io/bower/v/emojify.js.svg?style=flat-square
[ico-npm]: http://img.shields.io/npm/v/emojify.js.svg?style=flat-square
[ico-license]: http://img.shields.io/npm/l/emojify.js.svg?style=flat-square
[ico-gitter]: https://badges.gitter.im/hassankhan/emojify.js.svg
[license]: http://hassankhan.mit-license.org/
[gitter]: https://gitter.im/hassankhan/emojify.js

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