Twemoji Replacer for Rehype

A rehype plugin for replacing Unicode Emoji codepoints with images from jdecked/twemoji.

What is this?

This plugin extends the functionality of jdecked/twemoji to the unified (rehype) pipeline. It scans for Unicode Emoji codepoints in HTML content and replaces them with HTML <img> elements pointing to images of Emoji.

By default, it replaces Unicode Emoji codepoints with HTML <img> tags pointing to icons hosted on jsDelivr. However, this plugin exposes the options of the upstream jdecked/twemoji package so it is possible to change the URL to something else of your choice.

When should I use this?

This plugin ensures that usage of Emoji characters in your content appears normally and consistently in all kinds of client platforms.

Example Usage

Suppose that you have the following HTML content:

<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
😭 Vivamus iaculis eleifend ligula non blandit.
🇮🇸 Quisque ac ultrices elit. In iaculis mollis sagittis.
👨🏽‍🍼 Mauris a sapien blandit tortor porttitor scelerisque.
🏳️‍🌈 Donec molestie sapien orci, quis rutrum ante semper in.
👩‍🚀 Morbi bibendum elit vitae eros varius, sit amet tempus risus gravida.
❤️‍🔥 Phasellus non convallis nisi, non porta eros.
Nullam suscipit vel erat non eleifend.
</p>

With the plugin in the Rehype pipeline, the HTML output becomes:

<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<img class="emoji" draggable="false" alt="😭" src="https://cdn.jsdelivr.net/gh/jdecked/[email protected]/assets/72x72/1f62d.png"> Vivamus iaculis eleifend ligula non blandit.
<img class="emoji" draggable="false" alt="🇮🇸" src="https://cdn.jsdelivr.net/gh/jdecked/[email protected]/assets/72x72/1f1ee-1f1f8.png"> Quisque ac ultrices elit. In iaculis mollis sagittis.
<img class="emoji" draggable="false" alt="👨🏽‍🍼" src="https://cdn.jsdelivr.net/gh/jdecked/[email protected]/assets/72x72/1f468-1f3fd-200d-1f37c.png"> Mauris a sapien blandit tortor porttitor scelerisque.
<img class="emoji" draggable="false" alt="🏳️‍🌈" src="https://cdn.jsdelivr.net/gh/jdecked/[email protected]/assets/72x72/1f3f3-fe0f-200d-1f308.png"> Donec molestie sapien orci, quis rutrum ante semper in.
<img class="emoji" draggable="false" alt="👩‍🚀" src="https://cdn.jsdelivr.net/gh/jdecked/[email protected]/assets/72x72/1f469-200d-1f680.png"> Morbi bibendum elit vitae eros varius, sit amet tempus risus gravida.
<img class="emoji" draggable="false" alt="❤️‍🔥" src="https://cdn.jsdelivr.net/gh/jdecked/[email protected]/assets/72x72/2764-fe0f-200d-1f525.png"> Phasellus non convallis nisi, non porta eros.
Nullam suscipit vel erat non eleifend.
</p> 

Installation

To use the plugin, install both @abhabongse/rehype-replace-twemoji and its required peer dependency @twemoji/api (version 16.0.0 or higher). Head over to the package home page on JSR on how to install the plugin package itself.

# Install with npm 
npx jsr add @abhabongse/rehype-replace-twemoji
npm install @twemoji/api

# Install with pnpm 10.9+
pnpm i jsr:@abhabongse/rehype-replace-twemoji @twemoji/api

# Install with pnpm (older versions)
pnpm dlx jsr add @abhabongse/rehype-replace-twemoji
pnpm i @twemoji/api

# Install with yarn 4.9+
yarn add jsr:@abhabongse/rehype-replace-twemoji @twemoji/api

# Install with yarn (older versions)
yarn dlx jsr add @abhabongse/rehype-replace-twemoji
yarn add @twemoji/api

# Install with deno
deno add jsr:@abhabongse/rehype-replace-twemoji npm:@twemoji/api

# Install with bun
bunx jsr add @abhabongse/rehype-replace-twemoji
bun add @twemoji/api

Note

If you encounter peer dependency warnings, ensure you have @twemoji/api version 16.0.0 or higher installed. This package is required for the plugin to function properly.

To use the plugin in your pipeline, consult the relevant documentation with the keyword rehype.

• Astro
• MDX
• Next.js
• Nuxt Content

Customization via Options

If you wish to avoid using third-party CDNs or prefer SVG images, you can pass long options to the upstream jdecked/twemoji package.

const options = {
  className: "twemoji",
  callback(icon: string): string {
    return `/twemoji/${icon}.svg`;
  },
}

With these options, the original example HTML from above will be transformed into the following:

<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<img class="twemoji" draggable="false" alt="😭" src="/twemoji/1f62d.svg"> Vivamus iaculis eleifend ligula non blandit.
<img class="twemoji" draggable="false" alt="🇮🇸" src="/twemoji/1f1ee-1f1f8.svg"> Quisque ac ultrices elit. In iaculis mollis sagittis.
<img class="twemoji" draggable="false" alt="👨🏽‍🍼" src="/twemoji/1f468-1f3fd-200d-1f37c.svg"> Mauris a sapien blandit tortor porttitor scelerisque.
<img class="twemoji" draggable="false" alt="🏳️‍🌈" src="/twemoji/1f3f3-fe0f-200d-1f308.svg"> Donec molestie sapien orci, quis rutrum ante semper in.
<img class="twemoji" draggable="false" alt="👩‍🚀" src="/twemoji/1f469-200d-1f680.svg"> Morbi bibendum elit vitae eros varius, sit amet tempus risus gravida.
<img class="twemoji" draggable="false" alt="❤️‍🔥" src="/twemoji/2764-fe0f-200d-1f525.svg"> Phasellus non convallis nisi, non porta eros.
Nullam suscipit vel erat non eleifend.
</p>

API Reference

Head over to the JSR package documentation for the full API documentation.

Help, Support, and Contribute

If you are a user of this package, I would like to hear from you! Create a discussion thread or send me a direct message if you have feedback or suggestions.

License

Apache-2.0 © Abhabongse Janthong