Skip to main content

@mdit/plugin-emoji

Emoji plugin for markdown-it.

Usage

import { fullEmoji } from "@mdit/plugin-emoji";
import MarkdownIt from "markdown-it";

const mdIt = new MarkdownIt().use(fullEmoji);

mdIt.render("Hello from mars :satellite:");

Different presets are available:

  • fullEmoji: includes all available emojis support
  • lightEmoji: includes small subset of most useable emojis
  • bareEmoji: no defaults, only includes those you defined in options

A markdown-it instance supports one preset: reinstalling on the same instance — with another variant or with different options — keeps the first installed rule and its definitions.

Syntax

  • :emoji_name:
  • shortcuts like :), :D, etc. (if enabled)

Options

definitionsRecord<string, string>
Default{} (preset dependent)

Rewrite available emoji definitions. The key is the emoji name, and the value is the emoji character.

Example: { name1: 'char1', name2: 'char2', ... }

Untrusted input

Definition values are emitted as raw HTML into the output, so definitions must never contain untrusted user input, or the values must be sanitized first.

enabledstring[]
Default[]

If specified, only emojis in this list will be rendered. Otherwise, all emojis in the definitions will be rendered.

shortcutsRecord<string, string | string[]>
Default{} (preset dependent)

Rewrite default shortcuts. The key is the emoji name, and the value is the shortcut(s) for the emoji.

Empty or whitespace-only shortcuts are ignored.

Example: { "smile": [ ":)", ":-)" ], "laughing": ":D" }

Demo

Hello from mars 📡

Classic shortcuts: 😃 😦

Demo
Hello from mars :satellite:

Classic shortcuts: :-) :-(

Custom Renderer

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

For example, to use twemoji:

import { fullEmoji } from "@mdit/plugin-emoji";
import MarkdownIt from "markdown-it";
import twemoji from "twemoji";

const mdIt = new MarkdownIt().use(fullEmoji);

mdIt.renderer.rules.emoji = (tokens, idx) => twemoji.parse(tokens[idx].content);

And you can make image height match the line height with this style:

.emoji {
  height: 1.2em;
}

See the comparison report for the full upstream comparison.