API

What kind of emoji database would this be without a few helper functions for easily using and working with emoji characters? A bad one, and thus, a handful of functions can be found in the emojibase package.

yarn add emojibase

fetchFromCDN#

fetchFromCDN<T>(path: string, options?: FetchFromCDNOptions): Promise<T>

This function will fetch emojibase-data JSON files from our CDN, parse them, and return the response. It requires a file path relative to the emojibase-data package as the 1st argument and an optional object of options as the 2rd argument.

import { fetchFromCDN } from 'emojibase';
await fetchFromCDN('ja/compact.json', { version: '2.1.3' });

Only JSON datasets can be fetched from the CDN.

Options#

  • local (boolean) - Cache the response in local storage instead of session storage. Defaults to false.
  • version (string) - The release version to fetch. Defaults to latest.
  • All options supported by fetch.

fetchEmojis#

fetchEmojis(locale: Locale, options?: FetchEmojisOptions): Promise<Emoji[]>

Fetches and returns a localized list of emojis (and optional shortcodes) from our CDN. Uses fetchFromCDN and fetchShortcodes under the hood.

import { fetchEmojis } from 'emojibase';
await fetchEmojis('ja', {
compact: true,
shortcodes: ['cldr'],
version: '2.1.3',
});

It's also possible to load shortcodes from other languages by prefixing the shortcode preset with the chosen locale. This is useful if you want to support English and Japanese in parallel, for example.

await fetchEmojis('ja', {
shortcodes: ['cldr', 'en/cldr'],
});

Options#

  • compact (boolean) - Load the compact dataset instead of the full dataset. Defaults to false.
  • flat (boolean) - Flatten the dataset (moving skin tones to the root). Defaults to false.
  • shortcodes (string[]) - List of shortcode presets to load and merge into the emojis dataset. Defaults to an empty list.
  • All options supported by fetchFromCDN.

fetchMetadata#

fetchMetadata(locale: Locale options?: FetchFromCDNOptions): Promise<MetadataDataset>

Fetches and returns localized messages for emoji related information like groups and sub-groups. Uses fetchFromCDN under the hood.

import { fetchMetadata } from 'emojibase';
await fetchMetadata('zh', { version: '2.1.3' });

Options#

fetchShortcodes#

fetchShortcodes(locale: Locale, preset: ShortcodePreset, options?: FetchFromCDNOptions): Promise<ShortcodesDataset>

Fetches and returns localized shortcodes for the defined preset from our CDN. The response is a mapping of emoji hexcodes to shortcodes (either a string or array of strings). Uses fetchFromCDN under the hood.

import { fetchShortcodes } from 'emojibase';
await fetchShortcodes('ja', 'cldr', { version: '2.1.3' });

Options#

flattenEmojiData#

flattenEmojiData(data: Emoji[], shortcodeDatasets?: ShortcodesDataset[]): Emoji[]

By default, emoji skin modifications are nested under the base neutral skin tone emoji. To flatten the data into a single dimension array, use the flattenEmojiData function.

If shortcodeDatasets is defined, it will join the shortcodes to the emoji object using joinShortcodesToEmoji.

import { flattenEmojiData } from 'emojibase';
flattenEmojiData([
{
hexcode: '1F3CB-FE0F-200D-2642-FE0F',
// ...
skins: [
{
hexcode: '1F3CB-1F3FB-200D-2642-FE0F',
// ...
},
// ...
],
},
]);
/*
[
{
hexcode: '1F3CB-FE0F-200D-2642-FE0F',
// ...
},
{
hexcode: '1F3CB-1F3FB-200D-2642-FE0F',
// ...
},
]
*/

Tags from the parent emoji will be passed down to the skin modifications.

fromCodepointToUnicode#

fromCodepointToUnicode(codepoint: CodePoint[]): Unicode

This function will convert an array of numerical codepoints to a literal emoji Unicode character.

import { fromCodepointToUnicode } from 'emojibase';
fromCodepointToUnicode([128104, 8205, 128105, 8205, 128103, 8205, 128102]); // 馃懆鈥嶐煈┾嶐煈р嶐煈

fromHexcodeToCodepoint#

fromHexcodeToCodepoint(code: Hexcode, joiner?: string): CodePoint[]

This function will convert a hexadecimal codepoint to an array of numerical codepoints. By default, it will split the hexcode using a dash, but can be customized with the 2nd argument.

import { fromHexcodeToCodepoint } from 'emojibase';
fromHexcodeToCodepoint('270A-1F3FC'); // [9994, 127996]
fromHexcodeToCodepoint('270A 1F3FC', ' '); // [9994, 127996]

fromUnicodeToHexcode#

fromUnicodeToHexcode(unicode: Unicode, strip?: boolean): Hexcode

This function will convert a literal emoji Unicode character into a dash separated hexadecimal codepoint. Unless false is passed as the 2nd argument, zero width joiner's and variation selectors are removed.

import { fromUnicodeToHexcode } from 'emojibase';
fromUnicodeToHexcode('馃懆鈥嶐煈┾嶐煈р嶐煈'); // 1F468-1F469-1F467-1F466
fromUnicodeToHexcode('馃懆鈥嶐煈┾嶐煈р嶐煈', false); // 1F468-200D-1F469-200D-1F467-200D-1F466

generateEmoticonPermutations#

generateEmoticonPermutations(emoticon: Emoticon, options?: PermutationOptions): Emoticon[]

This function will generate multiple permutations of a base emoticon character. The following permutations will occur:

  • ) mouth will be replaced with ] and }. The same applies to sad/frowning mouths.
  • / mouth will be replaced with \.
  • : eyes will be replaced with =.
  • Supports a - nose, by injecting between the eyes and mouth.
  • Supports both uppercase and lowercase variants.
import { generateEmoticonPermutations } from 'emojibase';
generateEmoticonPermutations(':)'); // =-), =-}, :-], =-], :-}, :-), =}, =], =), :}, :], :)

The base emoticon must follow a set of naming guidelines to work properly.

Furthermore, this function accepts an options object as the 2nd argument, as a means to customize the output.

  • isFace (bool) - Toggles face permutations (mouth and eye variants). Defaults to true.
  • withNose (bool) - Toggles nose inclusion. Defaults to true.
generateEmoticonPermutations(':)', { withNose: false }); // =}, =], =), :}, :], :)
generateEmoticonPermutations('\\m/', { isFace: false }); // \m/, \M/

joinShortcodesToEmoji#

joinShortcodesToEmoji<T extends Emoji | CompactEmoji>(emoji: T, shortcodeDatasets: ShortcodesDataset[]): T

Will join shortcodes from multiple shortcode datasets into a single emoji object using its hexcode. Will remove duplicates in the process.

import { joinShortcodesToEmoji } from 'emojibase';
joinShortcodesToEmoji(
{
annotation: 'information',
name: 'INFORMATION SOURCE',
hexcode: '2139',
tags: ['i'],
emoji: '鈩癸笍',
// ...
},
[
{ '2139': 'information' /* ... */ },
{ '2139': 'info' /* ... */ },
{ '2139': 'info_source' /* ... */ },
{ '2139': 'info' /* ... */ },
],
);
/*
{
annotation: 'information',
name: 'INFORMATION SOURCE',
hexcode: '2139',
tags: ['i'],
emoji: '鈩癸笍',
shortcodes: ['information', 'info', 'info_source'],
// ...
}
*/

joinShortcodes#

joinShortcodes<T extends Emoji | CompactEmoji>(emojis: T[], shortcodeDatasets: ShortcodesDataset[]): T[]

Like joinShortcodesToEmoji but joins shortcodes to a list of emoji objects.

stripHexcode#

stripHexcode(hexcode: Hexcode): Hexcode

This function will strip zero width joiners (200D) and variation selectors (FE0E, FE0F) from a hexadecimal codepoint.

import { stripHexcode } from 'emojibase';
stripHexcode('1F468-200D-2695-FE0F'); // 1F468-2695