Skip to main content

Datasets

Emoji's are generated into JSON files called datasets, with each dataset being grouped into one of the following: localized data, versioned data, and metadata. These datasets can be found within the emojibase-data package, or loaded from a CDN.

yarn add emojibase-data

JSON files will need to be parsed manually unless handled by a build/bundle process.

Usage​

As stated, there are 3 groups of datasets, each serving a specific purpose. The first group, localized data, is exactly that, datasets with localization provided by CLDR (view supported locales). These datasets return an array of emoji objects that adhere to the defined data structure.

import emojis from 'emojibase-data/<locale>/data.json';
import compactEmojis from 'emojibase-data/<locale>/compact.json';
import groupsSubgroups from 'emojibase-data/<locale>/messages.json';

The second group, versioned data, provides datasets for emoji and Unicode release versions. These datasets return a map, with the key being the version, and the value being an array of emoji hexcodes included in the associated release version.

  • emojibase-data/versions/emoji.json - Emoji characters grouped by emoji version.
  • emojibase-data/versions/unicode.json - Emoji characters grouped by Unicode version.
import unicodeVersions from 'emojibase-data/versions/unicode.json';

The third and last group, metadata, provides specialized datasets for unique use cases.

  • emojibase-data/meta/groups.json - A map of non-localized emoji groups (Smileys & People), subgroups (Sky & Weather), and hierarchy, according to the official Unicode data files.
  • emojibase-data/meta/hexcodes.json - A map of emoji hexcodes (hexadecimal codepoints) to an object of hexcodes with different qualified status: fully qualified, minimally qualified, and unqualified.
  • emojibase-data/meta/unicode.json - An array of all emoji unicode characters, including text and emoji presentation characters.
  • emojibase-data/meta/unicode-names.json - A map of hexcodes to official Unicode names for each emoji.
import { groups, subgroups, hierarchy } from 'emojibase-data/meta/groups.json';

Data structure​

Each emoji character found within the pre-generated datasets are represented by an object composed of the properties listed below. In an effort to reduce the overall dataset filesize, most property values have been implemented using integers, with associated constants. View the Emoji object for a list of all available fields.

Not all properties will be found in the emoji object, as properties without an applicable value are omitted from the emoji object. This helps to reduce the filesize!

{
  annotation: 'man lifting weights',
  emoji: '🏋️‍♂️',
  gender: 1,
  group: 0,
  hexcode: '1F3CB-FE0F-200D-2642-FE0F',
  order: 1518,
  shortcodes: [
    'man_lifting_weights',
  ],
  subgroup: 0,
  tags: [
    'weight lifter',
    'man',
  ],
  type: 1,
  version: 4,
  skins: [
    {
      annotation: 'man lifting weights: light skin tone',
      emoji: '🏋🏻‍♂️',
      gender: 1,
      group: 0,
      hexcode: '1F3CB-1F3FB-200D-2642-FE0F',
      order: 1522,
      shortcodes: [
        'man_lifting_weights_tone1',
      ],
      subgroup: 0,
      type: 1,
      tone: 1,
      version: 4,
    },
    // ...
  ],
},

Compact format​

While the emoji data is pretty thorough, not all of it may be required, and as such, a compact dataset is supported. View the CompactEmoji object for a list of all available fields.

To use a compact dataset, replace data.json with compact.json.

import data from 'emojibase-data/en/compact.json';
{
  annotation: 'man lifting weights',
  group: 0,
  hexcode: '1F3CB-FE0F-200D-2642-FE0F',
  order: 1518,
  shortcodes: [
    'man_lifting_weights',
  ],
  tags: [
    'weight lifter',
    'man',
  ],
  unicode: '🏋️‍♂️',
  skins: [
    {
      annotation: 'man lifting weights: light skin tone',
      group: 0,
      hexcode: '1F3CB-1F3FB-200D-2642-FE0F',
      order: 1522,
      shortcodes: [
        'man_lifting_weights_tone1',
      ],
      unicode: '🏋🏻‍♂️',
    },
    // ...
  ],
},

Messages format​

The messages format is a special dataset that provides translations for groups, sub-groups, and any other related emoji metadata. The key in each message lines up with a defined TypeScript type alias.

import data from 'emojibase-data/en/messages.json';
{
  groups: [
    {
      key: 'smileys-emotion',
      message: 'smileys & emotion',
      order: 0,
    },
    // ...
  ],
  subgroups: [
    {
      key: 'face-smiling',
      message: 'smiling',
      order: 0,
    },
    // ...
  ],
  skinTones: [
    {
      key: 'light',
      message: 'light skin tone',
    },
    // ...
  ],
};

Fetching from a CDN​

If you prefer to not inflate your bundle size with these large JSON datasets, you can fetch them from our CDN (provided by jsdelivr.com) using fetchFromCDN(), fetchEmojis(), or fetchShortcodes().

import { fetchFromCDN, fetchEmojis, fetchMessages, fetchShortcodes } from 'emojibase';

const englishEmojis = await fetchFromCDN('en/data.json', { shortcodes: ['github'] });
const japaneseCompactEmojis = await fetchEmojis('ja', { compact: true });
const germanCldrShortcodes = await fetchShortcodes('de', 'cldr');
const chineseTranslations = await fetchMessages('zh');

Fetching from your own CDN​

If you want to load the JSON datasets from your own CDN, you can customize the cdnUrl using the options object.

When cdnUrl is a string, fetchFromCDN will append '/${path}' to the url. Make sure to include the version within the cdnUrl yourself, it's not added automatically to give you control over its placement.

import { fetchFromCDN, fetchEmojis, fetchMessages, fetchShortcodes } from 'emojibase';

const cdnUrl = 'https://example.com/cdn/emojidata/latest';

const englishEmojis = await fetchFromCDN('en/data.json', { shortcodes: ['github'], cdnUrl });
const japaneseCompactEmojis = await fetchEmojis('ja', { compact: true, cdnUrl });
const germanCldrShortcodes = await fetchShortcodes('de', 'cldr', { cdnUrl });
const chineseTranslations = await fetchMessages('zh', { cdnUrl });

cdnUrl can also be a function, so you have complete control over the format of the url. This function receives path and version as parameters. Version will be what you pass in within the options object, or it will default to latest. Note that version is also used for the cache key, so it's advised to set the option and not hard-code it in the cdnUrl function.

import { fetchFromCDN, fetchEmojis, fetchMessages, fetchShortcodes } from 'emojibase';

function cdnUrl(path: string, version: string): string {
  return `https://example.com/cdn/emojidata/${version}/${path}`;
}

const englishEmojis = await fetchFromCDN('en/data.json', { shortcodes: ['github'], cdnUrl });
const japaneseCompactEmojis = await fetchEmojis('ja', { compact: true, cdnUrl });
const germanCldrShortcodes = await fetchShortcodes('de', 'cldr', { cdnUrl });
const chineseTranslations = await fetchMessages('zh', { cdnUrl });

Supported locales​

Follow locales are supported for both full and compact datasets.

  • Bengali (bu)
  • Chinese (zh)
  • Chinese, Traditional (zh-hant)
  • Danish (da)
  • Dutch (nl)
  • English (en)
  • English, Great Britain (en-gb)
  • Estonian (et)
  • Finnish (fi)
  • French (fr)
  • German (de)
  • Hindu (hi)
  • Hungarian (hu)
  • Italian (it)
  • Japanese (ja)
  • Korean (ko)
  • Lithuanian (lt)
  • Malay (ms)
  • Norwegian (nb)
  • Polish (pl)
  • Portuguese (pt)
  • Russian (ru)
  • Spanish (es)
  • Spanish, Mexico (es-mx)
  • Swedish (sv)
  • Thai (th)
  • Ukrainian (uk)

Filesizes​

Sorted by original size in ascending order.

FileSizeGzipped
zh-hant/data.json650.85 kB74.35 kB
zh/data.json675.24 kB80.97 kB
da/data.json690.91 kB79.87 kB
sv/data.json692.51 kB80.97 kB
nb/data.json693.98 kB81.22 kB
en/data.json700.12 kB79.65 kB
en-gb/data.json700.17 kB79.65 kB
et/data.json705.97 kB80.32 kB
ko/data.json709.94 kB83.38 kB
fi/data.json710.5 kB84.29 kB
nl/data.json714.47 kB81.33 kB
ja/data.json714.67 kB84.08 kB
fr/data.json715.5 kB80.71 kB
lt/data.json718.09 kB84.13 kB
pt/data.json718.47 kB83.68 kB
ms/data.json726.38 kB81.26 kB
hu/data.json728.01 kB84.13 kB
es/data.json734.74 kB83.93 kB
es-mx/data.json735.55 kB84.14 kB
pl/data.json736.06 kB87.59 kB
it/data.json738.69 kB85.69 kB
de/data.json742.68 kB89.15 kB
ru/data.json862.11 kB94.85 kB
th/data.json870.25 kB84.56 kB
uk/data.json886.93 kB94.77 kB
hi/data.json916.45 kB91.43 kB
bn/data.json938.92 kB89.18 kB