Custom Emojis

Registration

Register custom emojis via the provider or per-instance. Each category contains an array of emojis with image sources.

@emoji-mart/data

import emojiMartData from '@emoji-mart/data';
import { fromEmojiMart } from 'react-emoji-text/adapters/emoji-mart';

const data = fromEmojiMart(emojiMartData);

<EmojiProvider
  data={data}
  customEmojis={[
    {
      id: 'custom',
      name: 'Custom',
      emojis: [
        {
          id: 'partyparrot',
          name: 'Party Parrot',
          keywords: ['party', 'parrot'],
          skins: [{ src: '/emojis/partyparrot.gif' }],
        },
      ],
    },
  ]}
>
  <EmojiText>:partyparrot:</EmojiText>
</EmojiProvider>

emojibase

import emojis from 'emojibase-data/en/data.json';
import shortcodes from 'emojibase-data/en/shortcodes/emojibase.json';
import { fromEmojibase } from 'react-emoji-text/adapters/emojibase';

const data = fromEmojibase(emojis, { shortcodes });

<EmojiProvider
  data={data}
  customEmojis={[
    {
      id: 'custom',
      name: 'Custom',
      emojis: [
        {
          id: 'partyparrot',
          name: 'Party Parrot',
          keywords: ['party', 'parrot'],
          skins: [{ src: '/emojis/partyparrot.gif' }],
        },
      ],
    },
  ]}
>
  <EmojiText>:partyparrot:</EmojiText>
</EmojiProvider>

Custom emojis render as <img> elements. If a custom emoji shares the same ID as a built-in emoji, the custom emoji takes precedence.

Custom Emoji Structure

Each custom emoji requires:

Field	Type	Description
id	string	Unique identifier, used as shortcode
name	string	Display name
keywords	string[] (optional)	Search keywords
skins	Array<{ src: string }>	Image sources (at least one required)

Aliasing Custom Emojis

Custom emojis can be referenced by extraAliases. Since custom emojis are indexed before aliases are resolved, aliases can point to custom emoji IDs:

<EmojiProvider data={data} customEmojis={customCategories} extraAliases={{ dance: 'partyparrot' }}>
  <EmojiText>:dance:</EmojiText> {/* renders the partyparrot image */}
</EmojiProvider>

Try It

Type any built-in shortcode to see it rendered:

@emoji-mart/dataemojibase

ASCII

hello 👋 world ❤️