Emojibase

https://github.com/milesj/emojibase
Admin
Emojibase is a comprehensive, localized emoji database providing pre-generated JSON datasets, regex...
Tokens:15,465
Snippets:97
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install emojibase-data with Yarn

Source: https://github.com/milesj/emojibase/blob/master/packages/data/README.md

Install the emojibase-data package using Yarn.

```bash
yarn add emojibase-data
```

--------------------------------

### Install emojibase-data with NPM

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

Install the emojibase-data package using NPM.

```bash
npm install emojibase-data
```

--------------------------------

### Install emojibase-regex with Yarn

Source: https://github.com/milesj/emojibase/blob/master/packages/regex/README.md

Install the emojibase-regex package using Yarn.

```bash
yarn add emojibase-regex
```

--------------------------------

### Install emojibase-regex with NPM

Source: https://github.com/milesj/emojibase/blob/master/website/docs/regex.mdx

Install the emojibase-regex package using NPM. This is an alternative to Yarn.

```bash
npm install emojibase-regex
```

--------------------------------

### Install emojibase-test-utils with yarn or npm

Source: https://github.com/milesj/emojibase/blob/master/packages/test-utils/README.md

Use yarn or npm to add emojibase-test-utils as a dev dependency. The commands are shown as alternatives.

```bash
yarn add emojibase-test-utils --dev
// Or
npm install emojibase-test-utils --save-dev
```

--------------------------------

### Full emoji object structure

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

Example of a full emoji object from the pre-generated datasets. Properties without applicable values are omitted to reduce filesize. The example shows the 'man lifting weights' emoji with its skins array.

```js
{
  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,
    },
    // ...
  ],
},
```

--------------------------------

### messages.po message example

Source: https://github.com/milesj/emojibase/blob/master/website/docs/translations.md

Example of a localized message for an emoji group. The # line shows the unique order and key, msgctxt indicates the context (EMOJI GROUP), msgid is the English text, and msgstr is the localized translation.

```python
# 1: people-body
msgctxt "EMOJI GROUP: people-body"
msgid "people & body"
msgstr "Menschen & Körper"

```

--------------------------------

### JSON example of combination skin tones in skins array

Source: https://github.com/milesj/emojibase/blob/master/website/docs/spec.md

Shows the structure of an emoji entry with multiple skin tone variants. The `skins` array can contain up to 15 variants, and the `tone` property may be an array of skin tones. This example is for the 'people holding hands' emoji.

```json
{
  "label": "people holding hands",
  "hexcode": "1F9D1-200D-1F91D-200D-1F9D1",
  // ...
  "skins": [
    {
      "label": "people holding hands: light skin tone",
      "hexcode": "1F9D1-1F3FB-200D-1F91D-200D-1F9D1-1F3FB",
      // ...
      "tone": 1
    },
    {
      "label": "people holding hands: medium-light skin tone, light skin tone",
      "hexcode": "1F9D1-1F3FC-200D-1F91D-200D-1F9D1-1F3FB",
      // ...
      "tone": [2, 1]
    },
    {
      "label": "people holding hands: medium-light skin tone",
      "hexcode": "1F9D1-1F3FC-200D-1F91D-200D-1F9D1-1F3FC",
      // ...
      "tone": 2
    },
    {
      "label": "people holding hands: medium skin tone, light skin tone",
      "hexcode": "1F9D1-1F3FD-200D-1F91D-200D-1F9D1-1F3FB",
      // ...
      "tone": [3, 1]
    },
    {
      "label": "people holding hands: medium skin tone, medium-light skin tone",
      "hexcode": "1F9D1-1F3FD-200D-1F91D-200D-1F9D1-1F3FC",
      // ...
      "tone": [3, 2]
    },
    {
      "label": "people holding hands: medium skin tone",
      "hexcode": "1F9D1-1F3FD-200D-1F91D-200D-1F9D1-1F3FD",
      // ...
      "tone": 3
    },
    {
      "label": "people holding hands: medium-dark skin tone, light skin tone",
      "hexcode": "1F9D1-1F3FE-200D-1F91D-200D-1F9D1-1F3FB",
      // ...
      "tone": [4, 1]
    },
    {
      "label": "people holding hands: medium-dark skin tone, medium-light skin tone",
      "hexcode": "1F9D1-1F3FE-200D-1F91D-200D-1F9D1-1F3FC",
      // ...
      "tone": [4, 2]
    },
    {
      "label": "people holding hands: medium-dark skin tone, medium skin tone",
      "hexcode": "1F9D1-1F3FE-200D-1F91D-200D-1F9D1-1F3FD",
      // ...
      "tone": [4, 3]
    },
    {
      "label": "people holding hands: medium-dark skin tone",
      "hexcode": "1F9D1-1F3FE-200D-1F91D-200D-1F9D1-1F3FE",
      // ...
      "tone": 4
    },
    {
      "label": "people holding hands: dark skin tone, light skin tone",
      "hexcode": "1F9D1-1F3FF-200D-1F91D-200D-1F9D1-1F3FB",
      // ...
      "tone": [5, 1]
    },
    {
      "label": "people holding hands: dark skin tone, medium-light skin tone",
      "hexcode": "1F9D1-1F3FF-200D-1F91D-200D-1F9D1-1F3FC",
      // ...
      "tone": [5, 2]
    },
    {
      "label": "people holding hands: dark skin tone, medium skin tone",
      "hexcode": "1F9D1-1F3FF-200D-1F91D-200D-1F9D1-1F3FD",
      // ...
      "tone": [5, 3]
    },
    {
      "label": "people holding hands: dark skin tone, medium-dark skin tone",
      "hexcode": "1F9D1-1F3FF-200D-1F91D-200D-1F9D1-1F3FE",
      // ...
      "tone": [5, 4]
    },
    {
      "label": "people holding hands: dark skin tone",
      "hexcode": "1F9D1-1F3FF-200D-1F91D-200D-1F9D1-1F3FF",
      // ...
      "tone": 5
    }
  ]
}
```

--------------------------------

### shortcodes.po message example

Source: https://github.com/milesj/emojibase/blob/master/website/docs/translations.md

Example of a localized shortcode for a snake emoji. The # line shows the emoji hexcode, msgctxt includes the emoji character and annotation, msgid is the English shortcode, and msgstr is the localized translation in lowercase with underscores.

```python
# 1F40D
msgctxt "EMOJI: 🐍 snake"
msgid "snake"
msgstr "змея"

```

--------------------------------

### Combination genders dataset example

Source: https://github.com/milesj/emojibase/blob/master/website/docs/spec.md

Shows combination gender emoji entries with distinct hexcodes. The men and women variants do not share a hexcode with the people emoji.

```json
{
  "label": "kiss",
  "hexcode": "1F48F"
  // ...
},
{
  "label": "kiss: woman, man",
  "hexcode": "1F469-200D-2764-FE0F-200D-1F48B-200D-1F468"
  // ...
},
{
  "label": "kiss: man, man",
  "hexcode": "1F468-200D-2764-FE0F-200D-1F48B-200D-1F468",
  // ...
},
{
  "label": "kiss: woman, woman",
  "hexcode": "1F469-200D-2764-FE0F-200D-1F48B-200D-1F469",
  // ...
},
```

--------------------------------

### cldr preset shortcode examples

Source: https://github.com/milesj/emojibase/blob/master/website/docs/shortcodes.md

Example shortcodes from the cldr preset for the emoji 😁 (beaming face with smiling eyes), showing English, Japanese, and Russian variants.

```text
// 😁 beaming face with smiling eyes
:beaming_face_with_smiling_eyes: // English
:ni_yatto_warau: // Japanese
:svetitsya_ot_schastya: // Russian
```

--------------------------------

### cldr-native preset shortcode examples

Source: https://github.com/milesj/emojibase/blob/master/website/docs/shortcodes.md

Example shortcodes from the cldr-native preset for the emoji 😁 (beaming face with smiling eyes), showing Korean and Ukrainian variants without Latin transliteration.

```text
// 😁 beaming face with smiling eyes
:미소_짓는_눈으로_웃는_얼굴: // Korean
:осяйно_всміхнене_обличчя_й_очі: // Ukrainian
```

--------------------------------

### Merged variation selectors dataset example

Source: https://github.com/milesj/emojibase/blob/master/website/docs/spec.md

Shows the raw dataset before v12 with duplicated variation selector entries, and the resulting merged structure where the emoji property includes the variation selector and text includes the text selector.

```json
{
  "00A9": {
    "description": "copyright",
    "hexcode": "00A9"
    // ...
  },
  "00A9-FE0F": {
    "description": "copyright",
    "hexcode": "00A9-FE0F"
    // ...
  }
}
```

```json
{
  "label": "copyright",
  "hexcode": "00A9",
  "emoji": "©️", // 00A9-FE0F
  "text": "©︎" // 00A9-FE0E
  // ...
}
```

--------------------------------

### Messages format structure

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

Example of the messages format dataset. The 'key' in each message lines up with a defined TypeScript type alias.

```js
{
  groups: [
    {
      key: 'smileys-emotion',
      message: 'smileys & emotion',
      order: 0,
    },
    // ...
  ],
  subgroups: [
    {
      key: 'face-smiling',
      message: 'smiling',
      order: 0,
    },
    // ...
  ],
  skinTones: [
    {
      key: 'light',
      message: 'light skin tone',
    },
    // ...
  ],
};
```

--------------------------------

### Compact emoji object structure

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

Example of a compact emoji object. It omits fields like 'emoji', 'gender', 'type', and 'version' compared to the full format, using 'unicode' instead of 'emoji'.

```js
{
  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: '🏋🏻‍♂️',
    },
    // ...
  ],
},
```

--------------------------------

### Separate genders dataset example

Source: https://github.com/milesj/emojibase/blob/master/website/docs/spec.md

Shows separate gender emoji entries with distinct hexcodes. The men and women variants always refer back to the people variant through a shared hexcode (1F9D6).

```json
{
  "label": "person in steamy room",
  "hexcode": "1F9D6"
  // ...
},
{
  "label": "man in steamy room",
  "hexcode": "1F9D6-200D-2642-FE0F"
  // ...
},
{
  "label": "woman in steamy room",
  "hexcode": "1F9D6-200D-2640-FE0F"
  // ...
},
```

--------------------------------

### Generate data files

Source: https://github.com/milesj/emojibase/blob/master/docs/add-new-language.md

Run this command to generate data files for the new locale. This may take a while; let it run to completion. Logs will be verbose, but scan for warnings/errors.

```shell
yarn run generate
```

--------------------------------

### Use fetchFromCDN with custom CDN string URL

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

When you want to load datasets from your own CDN, pass a string to `cdnUrl`. The library appends `'/path'` to the URL, but you must include the `version` in the URL yourself. `version` is not added automatically.

```ts
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 });

```

--------------------------------

### Build packages after adding locale

Source: https://github.com/milesj/emojibase/blob/master/docs/add-new-language.md

Run this command to rebuild packages after adding the new locale to the configuration files.

```shell
yarn run build
```

--------------------------------

### Use fetchFromCDN with custom CDN function URL

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

When you need complete control over the URL format, pass a function to `cdnUrl`. The function receives `path` and `version` parameters. `version` defaults to 'latest' if not set in the options. Note that `version` is also used as the cache key, so it's advised to set the option rather than hard-coding it.

```ts
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 });

```

--------------------------------

### Fetch datasets from CDN

Source: https://github.com/milesj/emojibase/blob/master/packages/data/README.md

Fetch datasets from the CDN using the emojibase package: fetchFromCDN for a specific file with shortcodes, fetchEmojis for compact data, and fetchShortcodes for CLDR shortcodes.

```typescript
import { fetchFromCDN, fetchEmojis, 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');
```

--------------------------------

### Import compact dataset

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

TypeScript import statement for the compact dataset. Replace 'data.json' with 'compact.json' to use the compact format.

```ts
import data from 'emojibase-data/en/compact.json';
```

--------------------------------

### Use fetchFromCDN with official CDN default

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

Demonstrates fetching emoji data from the default jsdelivr CDN. The fetchEmojis, fetchShortcodes, and fetchMessages functions default to the official CDN. Suitable when you don't need to customize the CDN location.

```ts
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');

```

--------------------------------

### Import property regex pattern

Source: https://github.com/milesj/emojibase/blob/master/website/docs/regex.mdx

Imports the property-based regex pattern from the property directory. These patterns are experimental and use at your own risk.

```ts
import PROPERTY_EMOJI_REGEX from 'emojibase-regex/property';
```

--------------------------------

### Import localized JSON dataset

Source: https://github.com/milesj/emojibase/blob/master/packages/data/README.md

Import the localized English JSON dataset directly from the package.

```typescript
import data from 'emojibase-data/en/data.json';
```

--------------------------------

### Import Unicode versioned dataset

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

Import the Unicode versioned dataset, which maps Unicode versions to arrays of emoji hexcodes.

```ts
import unicodeVersions from 'emojibase-data/versions/unicode.json';
```

--------------------------------

### Load flat emoji data using loadFlatEmojiData

Source: https://github.com/milesj/emojibase/blob/master/packages/test-utils/README.md

Imports loadFlatEmojiData from 'emojibase-test-utils' to return a flat array of emoji data where skin modifications are moved to the root.

```typescript
import { loadFlatEmojiData } from 'emojibase-test-utils';
```

--------------------------------

### Import and use emojibase-regex patterns

Source: https://github.com/milesj/emojibase/blob/master/packages/regex/README.md

Import the four regex patterns from emojibase-regex and use them with String.match to test emoji, emoticon, shortcode, and native shortcode matching.

```ts
import EMOJI_REGEX from 'emojibase-regex';
import EMOTICON_REGEX from 'emojibase-regex/emoticon';
import SHORTCODE_REGEX from 'emojibase-regex/shortcode';
import SHORTCODE_NATIVE_REGEX from 'emojibase-regex/shortcode-native';

`🏰`.match(EMOJI_REGEX);
':)'.match(EMOTICON_REGEX);
':castle:'.match(SHORTCODE_REGEX);
':гвинея:'.match(SHORTCODE_NATIVE_REGEX);
```

--------------------------------

### Import localized emoji datasets

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

Import localized emoji datasets from the emojibase-data package. The locale placeholder should be replaced with a supported locale code.

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

--------------------------------

### Import metadata groups dataset

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

Import the groups, subgroups, and hierarchy from the metadata groups dataset.

```ts
import { groups, subgroups, hierarchy } from 'emojibase-data/meta/groups.json';
```

--------------------------------

### Load emoji data using loadEmojiData

Source: https://github.com/milesj/emojibase/blob/master/packages/test-utils/README.md

Imports loadEmojiData from 'emojibase-test-utils' and iterates over the returned array of English emoji data.

```typescript
import { loadEmojiData } from 'emojibase-test-utils';

loadEmojiData().forEach((emoji) => {
  // Do something
});
```

--------------------------------

### Import codepoint regex pattern

Source: https://github.com/milesj/emojibase/blob/master/website/docs/regex.mdx

Imports the codepoint-aware regex pattern from the codepoint directory. The u (unicode) flag is required (defined by default) when using these patterns, and they are only supported in Node.js and modern browsers.

```ts
import CODEPOINT_EMOJI_REGEX from 'emojibase-regex/codepoint';
```

--------------------------------

### Import TypeScript types from emojibase

Source: https://github.com/milesj/emojibase/blob/master/website/docs/typescript.md

Use this import to access the TypeScript types provided by Emojibase. All types are available as named imports from the index of the emojibase package.

```TypeScript
import { Emoji, Emoticon, Shortcode } from 'emojibase';
```

--------------------------------

### Import messages dataset

Source: https://github.com/milesj/emojibase/blob/master/website/docs/datasets.mdx

TypeScript import statement for the messages dataset, which provides translations for groups, sub-groups, and other emoji metadata.

```ts
import data from 'emojibase-data/en/messages.json';
```
Tokens:
Raw