Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

remark-emoji

rhysd2.1mMIT5.0.1TypeScript support: included

Emoji transformer plugin for Remark

markdown, emoji, remark, plugin

readme

remark-emoji

CI npm

remark-emoji is a remark plugin to replace :emoji: to real UTF-8 emojis in Markdown text. This plugin is built on top of node-emoji. The accessibility support and Emoticon support are optionally available.

Demo

You can find a demo in the following Codesandbox.

Usage

remark().use(emoji [, options]);
import { remark } from 'remark';
import emoji from 'remark-emoji';

const doc = 'Emojis in this text will be replaced: :dog::+1:';
const processor = remark().use(emoji);
const file = await processor.process(doc);

console.log(String(file));
// => Emojis in this text will be replaced: 🐶👍

Note:

  • This package is ESM only from v3.0.0 since remark packages migrated to ESM.
  • This package supports Node.js v18 or later.

Options

options.accessible

Setting to true makes the converted emoji text accessible with role and aria-label attributes. Each emoji text is wrapped with <span> element. The role and aria-label attribute are not allowed by default. Please add them to the sanitization schema used by remark's HTML transformer. The default sanitization schema is exported from rehype-sanitize package.

For example,

import remarkParse from 'remark-parse';
import toRehype from 'remark-rehype';
import sanitize, { defaultSchema } from 'rehype-sanitize';
import stringify from 'rehype-stringify';
import emoji from 'remark-emoji';
import { unified } from 'unified';

// Allow using `role` and `aria-label` attributes in transformed HTML document
const schema = structuredClone(defaultSchema);
if ('span' in schema.attributes) {
    schema.attributes.span.push('role', 'ariaLabel');
} else {
    schema.attributes.span = ['role', 'ariaLabel'];
}

// Markdown text processor pipeline
const processor = unified()
    .use(remarkParse)
    .use(emoji, { accessible: true })
    .use(toRehype)
    .use(sanitize, schema)
    .use(stringify);

const file = await processor.process('Hello :dog:!');
console.log(String(file));

yields

Hello <span role="img" aria-label="dog emoji">🐶</span>!

Default value is false.

options.padSpaceAfter

Setting to true means that an extra whitespace is added after emoji. This is useful when browser handle emojis with half character length and following character is hidden. Default value is false.

options.emoticon

Setting to true means that emoticon shortcodes are supported (e.g. :-) will be replaced by 😃). Default value is false.

TypeScript support

remark-emoji package contains TypeScript type definitions. The package is ready for use with TypeScript.

Note that the legacy node (or node10) resolution at moduleResolution is not available since it enforces CommonJS module resolution and this package is ESM only. Please use node16, bundler, or nodenext to enable ESM module resolution.

License

Distributed under the MIT License.

changelog

v5.0.0 - 26 May 2024

  • Breaking change: Drop support for Node.js v16 or earlier following the Node.js maintenance cycle. Now this package supports Node.js v18 or later.
  • Migrate from JavaScript to TypeScript. Now the type definitions are generated by TypeScript compiler automatically. This is just an internal change and the APIs are preserved the same as in v4.0.1.
  • Avoid using legacy packages in example codes in the readme document.
  • The demo with Codesandbox was rebuilt from scratch with the latest Remark ecosystem and TypeScript.

Changes

v4.0.1 - 29 Oct 2023

  • Fix type definitions (#29)
    • This plugin is for transforming mdast (Markdown AST). Now it is explicitly defined as the 2nd type parameter of unified.Plugin.
    • @types/mdast and unified are now runtime dependencies. This ensures that the correct versions of those packages are referred by TypeScript compiler.

Changes

v4.0.0 - 10 Aug 2023

  • Breaking Change Update node-emoji from v1 to v2. This change introduces support for many new emojis and removes old emoji short codes which are no longer valid on GitHub.

Changes