# markdown-it-emoji

> Emoji plugin for markdown-it markdown parser.

Latest version **3.1.0** (published 2026-07-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install markdown-it-emoji
pnpm add markdown-it-emoji
yarn add markdown-it-emoji
bun add markdown-it-emoji
```

## Health

**Score 68/100 (B)** — status: active.

Positive: has types package; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.1.0 |
| Published | 2026-07-22 |
| First published | 2014-12-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/markdown-it-emoji) |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 336.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 769 |
| Maintainers | vitaly |
| Keywords | markdown-it-plugin, markdown-it, markdown, emoji, emojies, emoticon, emoticons |

## Links

- npm: https://www.npmjs.com/package/markdown-it-emoji
- Repository: https://github.com/markdown-it/markdown-it-emoji
- Homepage: https://github.com/markdown-it/markdown-it-emoji#readme
- Issues: https://github.com/markdown-it/markdown-it-emoji/issues
- npm.io page: https://npm.io/package/markdown-it-emoji

## Alternatives

- [@fortawesome/react-fontawesome](https://npm.io/package/@fortawesome/react-fontawesome.md) — 2.2M weekly downloads
- [roboto-fontface](https://npm.io/package/roboto-fontface.md) — 196.0K weekly downloads
- [@react-native-vector-icons/common](https://npm.io/package/@react-native-vector-icons/common.md) — 150.4K weekly downloads
- [@procore/core-icons](https://npm.io/package/@procore/core-icons.md) — 4.6K weekly downloads
- [@react-md/material-icons](https://npm.io/package/@react-md/material-icons.md) — 1.6K weekly downloads

## Recent versions

- 3.1.0 (latest) — 2026-07-22
- 3.0.0 — 2023-12-07
- 2.0.2 — 2022-04-22
- 2.0.1 — 2022-04-22
- 2.0.0 — 2020-10-14
- 1.4.0 — 2017-06-20
- 1.3.0 — 2016-10-04
- 1.2.0 — 2016-05-27
- 1.1.1 — 2016-03-24
- 1.1.0 — 2015-08-13
- 1.0.0 — 2015-03-12
- 0.1.3 — 2014-12-28
- 0.1.2 — 2014-12-24
- 0.1.1 — 2014-12-23
- 0.1.0 — 2014-12-21

## README

# markdown-it-emoji

[![CI](https://github.com/markdown-it/markdown-it-emoji/actions/workflows/ci.yml/badge.svg)](https://github.com/markdown-it/markdown-it-emoji/actions/workflows/ci.yml)
[![NPM version](https://img.shields.io/npm/v/markdown-it-emoji.svg?style=flat)](https://www.npmjs.org/package/markdown-it-emoji)
[![Coverage Status](https://coveralls.io/repos/markdown-it/markdown-it-emoji/badge.svg?branch=master&service=github)](https://coveralls.io/github/markdown-it/markdown-it-emoji?branch=master)

> Plugin for [markdown-it](https://github.com/markdown-it/markdown-it) markdown parser, adding emoji & emoticon syntax support. Also supports emoticons [shortcuts](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/shortcuts.mjs) like `:)`, `:-(`, and others.

__NOTE. v3 changed exports, see below.__


## Install

```bash
npm install markdown-it-emoji
```

## Use

### init

```js
//
// { full, light, bare } configs available.
//
//  full:  includes all available emojis support
//  light: includes small subset of most useable emojis
//  bare:  no defaults
//
// Also CJS & UMD builds available in `dist/` folder of published package,
// if your env not supports ESM modules use.
//
import { full as emoji } from 'markdown-it-emoji'
import markdownit from 'markdown-it'

const md = markdownit().use(emoji/* , options */);
```

Options are not mandatory:

- __defs__ (Object) - rewrite available emoji definitions
  - example: `{ name1: char1, name2: char2, ... }`
- __enabled__ (Array) - disable all emojis except whitelisted
- __shortcuts__ (Object) - rewrite default shortcuts
  - example: `{ "smile": [ ":)", ":-)" ], "laughing": ":D" }`

_Differences in browser._ If you load the script directly into the page without
using a package system, the module will add itself globally with the name `markdownitEmoji`.

### change output

By default, emojis are rendered as appropriate unicode chars. But you can change
the renderer function as you wish.

Render as span blocks (for example, to use a custom iconic font):

```js
// ...
// initialize

md.renderer.rules.emoji = function(token, idx) {
  return '<span class="emoji emoji_' + token[idx].markup + '"></span>';
};
```

Or use [twemoji](https://github.com/twitter/twemoji):

```js
// ...
// initialize

import twemoji from 'twemoji'

md.renderer.rules.emoji = function(token, idx) {
  return twemoji.parse(token[idx].content);
};
```

__NB 1__. Read [twemoji docs](https://github.com/twitter/twemoji#string-parsing)!
In case you need more options to change image size & type.

__NB 2__. When using twemoji you can make image height match the line height with this
style:

```css
.emoji {
  height: 1.2em;
}
```

### In your markdown file

```md
Hello from mars :satellite:
```

becomes

```
Hello from mars 📡
```

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