### Install emojibase-regex with NPM

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

Install the emojibase-regex package using NPM.

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

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

### Installation

Source: https://context7.com/milesj/emojibase/llms.txt

Instructions for installing the core utilities, pre-generated datasets, and regex patterns for Emojibase.

```APIDOC
## Installation

```bash
# Install core utilities
npm install emojibase

# Install pre-generated datasets
npm install emojibase-data

# Install regex patterns
npm install emojibase-regex
```
```

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

### Install Emojibase Regex

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 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 Packages

Source: https://context7.com/milesj/emojibase/llms.txt

Install the core utilities, pre-generated datasets, and regex patterns for Emojibase.

```bash
# Install core utilities
npm install emojibase
```

```bash
# Install pre-generated datasets
npm install emojibase-data
```

```bash
# Install regex patterns
npm install emojibase-regex
```

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

### Install Emojibase Data Package

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 Test Utils

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

Install the emojibase-test-utils package as a development dependency using either Yarn or npm.

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

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

### Emoji Data Structure Example

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

An example of the full emoji object structure found in the datasets. Properties with no applicable value are omitted to reduce file size.

```javascript
{
  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 Emoji Data Structure Example

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

An example of the compact emoji object structure. This format omits properties like 'emoji', 'gender', 'type', and 'version' to reduce file size.

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

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

### Translate Emoji Shortcodes

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

Example of a localized shortcode for an emoji in a .po file. Translations should be lowercase and use underscores, matching the msgid.

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

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

### Translate Emoji Group Messages

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

Example of a localized message for an emoji group in a .po file. Ensure translations match the msgid closely.

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

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

### Importing JSON Datasets

Source: https://context7.com/milesj/emojibase/llms.txt

Instructions on how to import pre-generated localized JSON datasets directly for bundled applications. Covers full and compact datasets, localized messages, shortcodes, versions, and metadata.

```APIDOC
## Importing JSON Datasets Directly

### Description
Import pre-generated localized JSON datasets directly for bundled applications. Available in full and compact formats for 28 locales.

### Available Datasets
- **Full Emoji Dataset**: Includes all properties for each emoji.
- **Compact Dataset**: Smaller filesize, fewer properties.
- **Localized Messages**: For groups, subgroups, and skin tones.
- **Shortcode Datasets**: For various platforms (GitHub, CLDR, native).
- **Version Datasets**: Emoji and Unicode version information.
- **Metadata Datasets**: Groups, subgroups, hierarchy, hexcodes, and Unicode characters.

### Import Examples
```typescript
// Full emoji dataset with all properties (English)
import emojis from 'emojibase-data/en/data.json';

// Compact dataset (smaller filesize, fewer properties) (English)
import compactEmojis from 'emojibase-data/en/compact.json';

// Localized messages (Japanese)
import messages from 'emojibase-data/ja/messages.json';

// Shortcode datasets
import githubShortcodes from 'emojibase-data/en/shortcodes/github.json';
import cldrShortcodes from 'emojibase-data/de/shortcodes/cldr.json';
import nativeShortcodes from 'emojibase-data/ko/shortcodes/cldr-native.json';

// Version datasets
import emojiVersions from 'emojibase-data/versions/emoji.json';
import unicodeVersions from 'emojibase-data/versions/unicode.json';

// Metadata datasets
import { groups, subgroups, hierarchy } from 'emojibase-data/meta/groups.json';
import hexcodes from 'emojibase-data/meta/hexcodes.json';
import unicodeChars from 'emojibase-data/meta/unicode.json';
```

### Available Locales
bn, da, de, en, en-gb, es, es-mx, et, fi, fr, hi, hu, it, ja, ko, lt, ms, nb, nl, pl, pt, ru, sv, th, uk, vi, zh, zh-hant
```

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

### Re-build Packages

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

Run this command after updating locale constants in various files to rebuild the Emojibase packages.

```shell
yarn run build
```

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

### Gather New Shortcode Entries

Source: https://github.com/milesj/emojibase/blob/master/docs/new-major-checklist.md

Run the 'generate:shortcodes' script to collect new shortcode entries for localization.

```bash
yarn generate:shortcodes
```

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

### Generate New Data

Source: https://github.com/milesj/emojibase/blob/master/docs/new-major-checklist.md

Run the 'generate' script to regenerate data after updating version constants. This step is crucial before proceeding with other updates.

```bash
yarn generate
```

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

### CLDR Shortcodes for Beaming Face

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

Examples of CLDR shortcodes for the 'beaming face with smiling eyes' emoji in English, Japanese, and Russian. These are derived from Unicode CLDR annotations and transliterated to Latin characters for non-Latin languages.

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

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

### CLDR-Native Shortcodes for Beaming Face

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

Examples of CLDR-native shortcodes for the 'beaming face with smiling eyes' emoji in Korean and Ukrainian. This preset avoids transliteration to Latin characters and excludes shortcodes already present in the standard CLDR preset.

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

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

### Generate Data Files

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

Execute this command after creating translation files to generate the necessary data files for the new locale. This process may take a significant amount of time.

```shell
yarn run generate
```

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

### Import Emojibase JSON Datasets

Source: https://context7.com/milesj/emojibase/llms.txt

Import pre-generated localized JSON datasets directly for bundled applications. Datasets are available in full and compact formats for 28 locales, along with specialized datasets for messages, shortcodes, versions, and metadata.

```typescript
// Full emoji dataset with all properties
import emojis from 'emojibase-data/en/data.json';

// Compact dataset (smaller filesize, fewer properties)
import compactEmojis from 'emojibase-data/en/compact.json';

// Localized messages (groups, subgroups, skin tones)
import messages from 'emojibase-data/ja/messages.json';

// Shortcode datasets
import githubShortcodes from 'emojibase-data/en/shortcodes/github.json';
import cldrShortcodes from 'emojibase-data/de/shortcodes/cldr.json';
import nativeShortcodes from 'emojibase-data/ko/shortcodes/cldr-native.json';

// Version datasets
import emojiVersions from 'emojibase-data/versions/emoji.json';
import unicodeVersions from 'emojibase-data/versions/unicode.json';

// Metadata datasets
import { groups, subgroups, hierarchy } from 'emojibase-data/meta/groups.json';
import hexcodes from 'emojibase-data/meta/hexcodes.json';
import unicodeChars from 'emojibase-data/meta/unicode.json';

// Available locales: bn, da, de, en, en-gb, es, es-mx, et, fi, fr, hi, hu,
// it, ja, ko, lt, ms, nb, nl, pl, pt, ru, sv, th, uk, vi, zh, zh-hant
```

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

### Fetch Emojis with Options

Source: https://context7.com/milesj/emojibase/llms.txt

Fetch localized emojis with options for shortcodes, compactness, and data flattening. Requires importing 'fetchEmojis' from 'emojibase'.

```typescript
import { fetchEmojis } from 'emojibase';

// Fetch English emojis with GitHub shortcodes
const emojis = await fetchEmojis('en', {
  shortcodes: ['github']
});
```

```typescript
// Fetch compact Japanese emojis with multiple shortcode presets
const compactEmojis = await fetchEmojis('ja', {
  compact: true,
  shortcodes: ['cldr', 'emojibase']
});
```

```typescript
// Fetch flattened data (skin tones at root level) with cross-locale shortcodes
const flatEmojis = await fetchEmojis('de', {
  flat: true,
  shortcodes: ['cldr', 'en/github']  // German CLDR + English GitHub shortcodes
});
```

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

### fetchShortcodes

Source: https://context7.com/milesj/emojibase/llms.txt

Fetches and returns localized shortcodes for a specific preset from the CDN. Returns a mapping of emoji hexcodes to shortcodes (string or array of strings).

```APIDOC
## fetchShortcodes

### Description
Fetches and returns localized shortcodes for a specific preset from the CDN. Returns a mapping of emoji hexcodes to shortcodes (string or array of strings).

### Method
`fetchShortcodes(locale: string, preset: string)`

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code for the desired language (e.g., 'en', 'ja', 'de').
- **preset** (string) - Required - The shortcode preset to fetch (e.g., 'cldr', 'github', 'joypixels', 'iamcal', 'cldr-native').

### Request Example
```typescript
import { fetchShortcodes } from 'emojibase';

// Fetch CLDR shortcodes for German
const germanShortcodes = await fetchShortcodes('de', 'cldr');

// Fetch GitHub shortcodes for English
const githubShortcodes = await fetchShortcodes('en', 'github');

// Fetch JoyPixels/Discord shortcodes
const discordShortcodes = await fetchShortcodes('en', 'joypixels');

// Fetch Slack/iamcal shortcodes
const slackShortcodes = await fetchShortcodes('en', 'iamcal');

// Fetch native language shortcodes (non-Latin characters)
const koreanNative = await fetchShortcodes('ko', 'cldr-native');
```

### Response
#### Success Response (200)
- Returns an object where keys are emoji hexcodes and values are either a string or an array of strings representing the shortcodes for that emoji.

#### Response Example
```json
{
  "1F600": "grinning",
  "1F601": ["beaming_face_with_smiling_eyes", "grin"],
  "1F602": "face_with_tears_of_joy"
}
```
```

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

### Fetch Data from Custom CDN URL

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

Configure the 'cdnUrl' option to fetch data from your own CDN. The URL can be a string, and the version is appended automatically.

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

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

### Import Compact Emoji Data

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

Import a compact version of the emoji dataset by replacing `data.json` with `compact.json`. This reduces file size by omitting certain properties.

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

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

### Import Localized JSON Dataset

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

Import a localized JSON dataset directly into your project. Ensure the correct language path is used.

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

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

### Generate Types

Source: https://github.com/milesj/emojibase/blob/master/docs/new-major-checklist.md

Run the 'generate:types' script to update type definitions. Copy the GroupKey and SubgroupKey types to the specified location.

```bash
yarn generate:types
```

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

### fetchEmojis

Source: https://context7.com/milesj/emojibase/llms.txt

Fetches and returns a localized list of emojis with optional shortcodes from the CDN. This is the primary method for loading emoji data in browser applications, combining `fetchFromCDN` and `fetchShortcodes` under the hood with built-in caching via sessionStorage.

```APIDOC
## fetchEmojis

### Description
Fetches and returns a localized list of emojis with optional shortcodes from the CDN. This is the primary method for loading emoji data in browser applications, combining `fetchFromCDN` and `fetchShortcodes` under the hood with built-in caching via sessionStorage.

### Method
`fetchEmojis(locale: string, options?: object)`

### Parameters
#### Query Parameters
- **locale** (string) - Required - The locale code for the desired language (e.g., 'en', 'ja', 'de').
- **options** (object) - Optional - Configuration options:
  - **shortcodes** (array<string>) - Optional - An array of shortcode presets to include (e.g., ['github'], ['cldr', 'emojibase']).
  - **compact** (boolean) - Optional - If true, returns a more compact dataset.
  - **flat** (boolean) - Optional - If true, skin tones are included at the root level of the dataset.

### Request Example
```typescript
import { fetchEmojis } from 'emojibase';

// Fetch English emojis with GitHub shortcodes
const emojis = await fetchEmojis('en', {
  shortcodes: ['github']
});

// Fetch compact Japanese emojis with multiple shortcode presets
const compactEmojis = await fetchEmojis('ja', {
  compact: true,
  shortcodes: ['cldr', 'emojibase']
});

// Fetch flattened data (skin tones at root level) with cross-locale shortcodes
const flatEmojis = await fetchEmojis('de', {
  flat: true,
  shortcodes: ['cldr', 'en/github']  // German CLDR + English GitHub shortcodes
});
```

### Response
#### Success Response (200)
- **emoji** (string) - The emoji character.
- **hexcode** (string) - The Unicode hex code of the emoji.
- **label** (string) - The localized label for the emoji.
- **group** (number) - The group identifier for the emoji.
- **order** (number) - The display order within its group.
- **shortcodes** (array<string>) - An array of associated shortcodes.
- **tags** (array<string>) - An array of tags associated with the emoji.
- **version** (number) - The Unicode version the emoji was introduced.
- **type** (number) - The type of emoji (e.g., 1 for component, 2 for component).

#### Response Example
```json
{
  "emoji": "😀",
  "hexcode": "1F600",
  "label": "grinning face",
  "group": 0,
  "order": 1,
  "shortcodes": ["grinning", "grinning_face"],
  "tags": ["face", "grin"],
  "version": 1,
  "type": 1
}
```
```

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

### Fetch Localized Shortcodes

Source: https://context7.com/milesj/emojibase/llms.txt

Fetch localized shortcodes for specific presets from the CDN. Returns a mapping of emoji hexcodes to shortcodes. Requires importing 'fetchShortcodes' from 'emojibase'.

```typescript
import { fetchShortcodes } from 'emojibase';

// Fetch CLDR shortcodes for German
const germanShortcodes = await fetchShortcodes('de', 'cldr');
```

```typescript
// Fetch GitHub shortcodes for English
const githubShortcodes = await fetchShortcodes('en', 'github');
```

```typescript
// Fetch JoyPixels/Discord shortcodes
const discordShortcodes = await fetchShortcodes('en', 'joypixels');
```

```typescript
// Fetch Slack/iamcal shortcodes
const slackShortcodes = await fetchShortcodes('en', 'iamcal');
```

```typescript
// Fetch native language shortcodes (non-Latin characters)
const koreanNative = await fetchShortcodes('ko', 'cldr-native');
```

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

### Fetch Emojis from CDN

Source: https://context7.com/milesj/emojibase/llms.txt

Fetch Emojibase JSON datasets from a CDN with automatic caching. Supports custom CDN URLs and version pinning. Requires importing 'fetchFromCDN' from 'emojibase'.

```typescript
import { fetchFromCDN } from 'emojibase';

// Fetch full English dataset (latest version)
const englishData = await fetchFromCDN('en/data.json');
```

```typescript
// Fetch compact Japanese dataset with specific version
const japaneseCompact = await fetchFromCDN('ja/compact.json', {
  version: '15.0.0'
});
```

```typescript
// Use localStorage instead of sessionStorage for persistent caching
const cachedData = await fetchFromCDN('en/data.json', {
  local: true
});
```

```typescript
// Use custom CDN URL (string format)
const customData = await fetchFromCDN('en/data.json', {
  cdnUrl: 'https://my-cdn.example.com/emojibase/v15'
});
```

```typescript
// Use custom CDN URL (function format for full control)
const dynamicData = await fetchFromCDN('en/data.json', {
  version: '15.0.0',
  cdnUrl: (path, version) => `https://my-cdn.example.com/${version}/${path}`
});
```

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

### Import and Use Emojibase Regex Patterns

Source: https://context7.com/milesj/emojibase/llms.txt

Import and utilize various regex patterns from 'emojibase-regex' to match emoji characters, emoticons, and shortcodes. Handles complex emoji variations like skin tones.

```typescript
import EMOJI_REGEX from 'emojibase-regex';

import EMOJI_ONLY from 'emojibase-regex/emoji';
import TEXT_ONLY from 'emojibase-regex/text';

import EMOJI_LOOSE from 'emojibase-regex/emoji-loose';
import TEXT_LOOSE from 'emojibase-regex/text-loose';

import EMOTICON_REGEX from 'emojibase-regex/emoticon';
import SHORTCODE_REGEX from 'emojibase-regex/shortcode';
import SHORTCODE_NATIVE from 'emojibase-regex/shortcode-native';

import CODEPOINT_REGEX from 'emojibase-regex/codepoint';
```

```typescript
const text = 'Hello 😀 world! :) :wave:';

// Match emoji characters
const emojiMatches = text.match(new RegExp(EMOJI_REGEX.source, 'g'));
// ['😀']

// Match emoticons
const emoticonMatches = ':) :( ;)'.match(new RegExp(EMOTICON_REGEX.source, 'g'));
// [':)', ':(', ';)']

// Match shortcodes
const shortcodeMatches = ':wave: :smile:'.match(new RegExp(SHORTCODE_REGEX.source, 'g'));
// [':wave:', ':smile:']

// Match native language shortcodes
':гвинея:'.match(SHORTCODE_NATIVE);  // [':гвинея:']

// Complex matching with skin tones
'👍🏻 great job!'.match(EMOJI_REGEX);  // ['👍🏻']
```

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

### fetchFromCDN

Source: https://context7.com/milesj/emojibase/llms.txt

Fetches emojibase-data JSON files from a CDN, parses them, and returns the response with automatic caching. Supports custom CDN URLs and version pinning for production deployments.

```APIDOC
## fetchFromCDN

### Description
Fetches emojibase-data JSON files from a CDN, parses them, and returns the response with automatic caching. Supports custom CDN URLs and version pinning for production deployments.

### Method
`fetchFromCDN(path: string, options?: object)`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the JSON file on the CDN (e.g., 'en/data.json', 'ja/compact.json').

#### Query Parameters
- **options** (object) - Optional - Configuration options:
  - **version** (string) - Optional - The specific version of the dataset to fetch (e.g., '15.0.0').
  - **local** (boolean) - Optional - If true, uses localStorage instead of sessionStorage for caching.
  - **cdnUrl** (string | function) - Optional - A custom CDN URL or a function to generate it.

### Request Example
```typescript
import { fetchFromCDN } from 'emojibase';

// Fetch full English dataset (latest version)
const englishData = await fetchFromCDN('en/data.json');

// Fetch compact Japanese dataset with specific version
const japaneseCompact = await fetchFromCDN('ja/compact.json', {
  version: '15.0.0'
});

// Use localStorage instead of sessionStorage for persistent caching
const cachedData = await fetchFromCDN('en/data.json', {
  local: true
});

// Use custom CDN URL (string format)
const customData = await fetchFromCDN('en/data.json', {
  cdnUrl: 'https://my-cdn.example.com/emojibase/v15'
});

// Use custom CDN URL (function format for full control)
const dynamicData = await fetchFromCDN('en/data.json', {
  version: '15.0.0',
  cdnUrl: (path, version) => `https://my-cdn.example.com/${version}/${path}`
});
```

### Response
#### Success Response (200)
- The response will be the parsed JSON content of the requested file from the CDN.
```

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

### Import Metadata Groups

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

Import emoji groups, subgroups, and hierarchy data from the emojibase-data/meta directory. This data is non-localized.

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

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

### Fetch Emojis and Data from CDN

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

Use fetch functions to retrieve emoji data, shortcodes, or messages from the Emojibase CDN. Specify locale and options like 'compact' or 'shortcodes'.

```typescript
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 and Use Emojibase Regex Patterns

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

Import and utilize different regular expression patterns provided by the emojibase-regex package for matching emojis, emoticons, and shortcodes.

```typescript
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);
```

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

### Fetch Data with Function-based Custom CDN URL

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

Provide a function for 'cdnUrl' for complete control over URL formatting, receiving 'path' and 'version' as arguments.

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

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

### Import and Use Emojibase Constants

Source: https://context7.com/milesj/emojibase/llms.txt

Import and use constants for emoji presentation types, genders, skin tones, and group keys. Useful for filtering and categorizing emojis.

```typescript
import {
  TEXT,
  EMOJI,

  FEMALE,
  MALE,

  LIGHT_SKIN,
  MEDIUM_LIGHT_SKIN,
  MEDIUM_SKIN,
  MEDIUM_DARK_SKIN,
  DARK_SKIN,

  GROUP_KEY_SMILEYS_EMOTION,
  GROUP_KEY_PEOPLE_BODY,
  GROUP_KEY_ANIMALS_NATURE,
  GROUP_KEY_FOOD_DRINK,
  GROUP_KEY_TRAVEL_PLACES,
  GROUP_KEY_ACTIVITIES,
  GROUP_KEY_OBJECTS,
  GROUP_KEY_SYMBOLS,
  GROUP_KEY_FLAGS,
  GROUP_KEY_COMPONENT,

  LATEST_EMOJI_VERSION,
  LATEST_UNICODE_VERSION,
  LATEST_CLDR_VERSION,
  EMOJI_VERSIONS,
  UNICODE_VERSIONS,
  SUPPORTED_LOCALES,
} from 'emojibase';
```

```typescript
// Example: Filter emojis by type
const emojiPresentation = emojis.filter(e => e.type === EMOJI);

// Example: Filter by skin tone
const lightSkinEmojis = emojis.filter(e => e.tone === LIGHT_SKIN);

// Example: Filter by group
const smileyEmojis = emojis.filter(e => e.group === 0); // smileys-emotion
```

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

### fromHexcodeToCodepoint

Source: https://context7.com/milesj/emojibase/llms.txt

Converts a hexadecimal codepoint string to an array of numerical codepoints. Supports custom joiners for different hexcode formats.

```APIDOC
## fromHexcodeToCodepoint

### Description
Converts a hexadecimal codepoint string to an array of numerical codepoints. Supports custom joiners for different hexcode formats.

### Method
`fromHexcodeToCodepoint(hexcode: string, joiner: string = '-'): number[]

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { fromHexcodeToCodepoint } from 'emojibase';

// Standard dash-separated hexcode
fromHexcodeToCodepoint('1F600');  // [128512]

// Multi-codepoint emoji (skin tone)
fromHexcodeToCodepoint('270A-1F3FC');  // [9994, 127996]

// Space-separated format
fromHexcodeToCodepoint('270A 1F3FC', ' ');  // [9994, 127996]

// Family emoji
fromHexcodeToCodepoint('1F468-1F469-1F467-1F466');  // [128104, 128105, 128103, 128102]
```

### Response
#### Success Response (200)
- **number[]** - An array of numerical codepoints.

#### Response Example
```
[128512]
[9994, 127996]
[128104, 128105, 128103, 128102]
```
```

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

### Import and Use Emoji Regex Patterns

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

Import and utilize various regex patterns from emojibase-regex to match emoji, emoticons, and shortcodes. Note that the 'u' and 'g' flags are not defined by default.

```typescript
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);
':pleased:'.match(SHORTCODE_REGEX);
':гвинея:'.match(SHORTCODE_NATIVE_REGEX);
```

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

### Import and Use Property Emoji Regex

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

Import and use regex patterns that leverage Unicode property escapes for emoji matching. Use with caution as this feature is still a proposal.

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

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

### fromCodepointToUnicode

Source: https://context7.com/milesj/emojibase/llms.txt

Converts an array of numerical codepoints to a literal emoji Unicode character string. Supports simple emojis, skin tone emojis, and complex emojis with Zero-Width Joiners (ZWJ).

```APIDOC
## fromCodepointToUnicode

### Description
Converts an array of numerical codepoints to a literal emoji Unicode character string.

### Method
`fromCodepointToUnicode`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **codepoints** (number[]) - Required - An array of numerical codepoints.

### Request Example
```typescript
import { fromCodepointToUnicode } from 'emojibase';

// Simple emoji
fromCodepointToUnicode([128512]);

// Skin tone emoji
fromCodepointToUnicode([9994, 127996]);

// Family emoji with ZWJ
fromCodepointToUnicode([128104, 8205, 128105, 8205, 128103, 8205, 128102]);
```

### Response
#### Success Response (200)
- **unicodeString** (string) - The resulting Unicode character string.

#### Response Example
```json
"😀"
```

### Additional Notes
Can be used for round-trip conversions with `fromHexcodeToCodepoint`.
```

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

### fetchMessages

Source: https://context7.com/milesj/emojibase/llms.txt

Fetches and returns localized messages for emoji-related metadata including groups, subgroups, and skin tones. Useful for building emoji pickers with localized category labels.

```APIDOC
## fetchMessages

### Description
Fetches and returns localized messages for emoji-related metadata including groups, subgroups, and skin tones. Useful for building emoji pickers with localized category labels.

### Method
`fetchMessages(locale: string, options?: { version?: string }): Promise<Messages>

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { fetchMessages } from 'emojibase';

// Fetch Chinese translations for groups and metadata
const chineseMessages = await fetchMessages('zh');

// Fetch French messages with specific version
const frenchMessages = await fetchMessages('fr', { version: '15.0.0' });
```

### Response
#### Success Response (200)
- **groups** (Array<MessageItem>) - Localized group names and order.
- **subgroups** (Array<MessageItem>) - Localized subgroup names and order.
- **skinTones** (Array<MessageItem>) - Localized skin tone names.

#### Response Example
```json
{
  "groups": [
    { "key": "smileys-emotion", "message": "smileys & emotion", "order": 0 },
    { "key": "people-body", "message": "people & body", "order": 1 },
    ...
  ],
  "subgroups": [
    { "key": "face-smiling", "message": "smiling", "order": 0 },
    ...
  ],
  "skinTones": [
    { "key": "light", "message": "light skin tone" },
    { "key": "medium", "message": "medium skin tone" },
    ...
  ]
}
```
```

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

### appendSkinToneIndex

Source: https://context7.com/milesj/emojibase/llms.txt

Appends a skin tone index to the end of a shortcode for skin tone variations. Handles both single and multi-person skin tones.

```APIDOC
## appendSkinToneIndex

### Description
Appends a skin tone index to the end of a shortcode for skin tone variations. Handles both single and multi-person skin tones.

### Method
`appendSkinToneIndex`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **shortcode** (string) - Required - The base emoji shortcode.
- **emojiData** (object) - Required - An object containing skin tone information.
  - **tone** (number | number[]) - Required - The skin tone index (1-5) or an array of indices for multi-person emojis.
- **prefix** (string) - Optional - A custom prefix to use before the skin tone index. Defaults to an empty string.

### Request Example
```typescript
import { appendSkinToneIndex } from 'emojibase';

// Single skin tone
const emoji = { tone: 1 };  // light skin
appendSkinToneIndex('thumbs_up', emoji);

// Medium-dark skin tone
const mediumDark = { tone: 4 };
appendSkinToneIndex('wave', mediumDark);

// Multi-person skin tones (handshake between different tones)
const multiTone = { tone: [1, 5] };  // light + dark
appendSkinToneIndex('handshake', multiTone);

// With custom prefix
appendSkinToneIndex('thumbs_up', emoji, 'tone');
```

### Response
#### Success Response (200)
- **modifiedShortcode** (string) - The shortcode with the skin tone index appended.

#### Response Example
```json
"thumbs_up_1"
```
```

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

### Fetch Emojibase Data from CDN

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

Fetch emoji data from the Emojibase CDN. Supports fetching specific datasets like data.json, emojis, or shortcodes with various options for localization and format.

```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 Localized Emoji Data

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

Import localized emoji data from the emojibase-data package. Ensure you replace <locale> with the desired language code.

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

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

### joinShortcodesToEmoji

Source: https://context7.com/milesj/emojibase/llms.txt

Joins shortcodes from multiple shortcode datasets into a single emoji object using its hexcode. Removes duplicates and handles nested skin variations.

```APIDOC
## joinShortcodesToEmoji

### Description
Joins shortcodes from multiple shortcode datasets into a single emoji object using its hexcode. Removes duplicates and handles nested skin variations.

### Method
`joinShortcodesToEmoji(emoji: Emoji, shortcodes: Shortcode[][]): Emoji

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { joinShortcodesToEmoji, fetchShortcodes } from 'emojibase';

// Load multiple shortcode datasets
const githubCodes = await fetchShortcodes('en', 'github');
const emojibaseCodes = await fetchShortcodes('en', 'emojibase');

const emoji = {
  hexcode: '1F600',
  emoji: '😀',
  label: 'grinning face',
  shortcodes: []
};

// Join shortcodes from multiple sources
const enrichedEmoji = joinShortcodesToEmoji(emoji, [githubCodes, emojibaseCodes]);
```

### Response
#### Success Response (200)
- **emoji** (Emoji) - The emoji object with combined and deduplicated shortcodes.

#### Response Example
```json
// Result:
// {
//   "hexcode": "1F600",
//   "emoji": "😀",
//   "label": "grinning face",
//   "shortcodes": ["grinning", "grinning_face"]  // Combined and deduplicated
// }
```
```

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

### Load Flat Emoji Data

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

Use `loadFlatEmojiData` to obtain a flattened array of emoji data. Skin tone modifications are included at the root level in this format.

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

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

### Import and Use Emojibase TypeScript Types

Source: https://context7.com/milesj/emojibase/llms.txt

Import and utilize comprehensive TypeScript types for Emojibase emoji data structures, properties, and options. Enables type-safe emoji handling.

```typescript
import type {
  Emoji,
  CompactEmoji,
  FlatEmoji,
  FlatCompactEmoji,

  Hexcode,
  Unicode,
  Shortcode,
  Emoticon,
  CodePoint,

  Gender,
  SkinTone,
  Presentation,
  Group,
  Subgroup,

  GroupKey,
  SubgroupKey,
  SkinToneKey,
  GenderKey,
  PresentationKey,

  Locale,
  ShortcodePreset,
  LocalizedShortcodePreset,

  ShortcodesDataset,
  MessagesDataset,
  GroupDataset,
  VersionDataset,

  GroupMessage,
  SubgroupMessage,
  SkinToneMessage,

  FetchFromCDNOptions,
  FetchEmojisOptions,
  PermutationOptions,
} from 'emojibase';
```

```typescript
// Example: Typed emoji handler
function handleEmoji(emoji: Emoji): void {
  console.log(`${emoji.emoji} - ${emoji.label}`);
  if (emoji.shortcodes) {
    console.log(`Shortcodes: ${emoji.shortcodes.join(', ')}`);
  }
  if (emoji.skins) {
    emoji.skins.forEach((skin: Emoji) => {
      console.log(`  Skin tone ${skin.tone}: ${skin.emoji}`);
    });
  }
}
```

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

### Import and Use Codepoint Emoji Regex

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

Import and use codepoint-aware regex patterns for emoji matching. These patterns require the 'u' (unicode) flag, which is defined by default. Supported in Node.js and modern browsers.

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

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

### Import Emojibase Types

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

Import necessary types like `Emoji`, `Emoticon`, and `Shortcode` from the `emojibase` package for use in your TypeScript code.

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

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

### Update Version Constants

Source: https://github.com/milesj/emojibase/blob/master/docs/new-major-checklist.md

Update the LATEST_EMOJI_VERSION, LATEST_UNICODE_VERSION, LATEST_CLDR_VERSION, EMOJI_VERSIONS, and UNICODE_VERSIONS constants according to the specified versioning formats.

```javascript
const LATEST_EMOJI_VERSION = "x.x";
const LATEST_UNICODE_VERSION = "x.x.x";
const LATEST_CLDR_VERSION = "x";
const EMOJI_VERSIONS = ["x.x"];
const UNICODE_VERSIONS = ["x.x"];
```

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

### Join Shortcodes to a Single Emoji

Source: https://context7.com/milesj/emojibase/llms.txt

Joins shortcodes from multiple datasets into a single emoji object based on its hexcode. It handles deduplication and nested skin variations. Requires an initial emoji object and an array of shortcode datasets.

```typescript
import { joinShortcodesToEmoji, fetchShortcodes } from 'emojibase';

// Load multiple shortcode datasets
const githubCodes = await fetchShortcodes('en', 'github');
const emojibaseCodes = await fetchShortcodes('en', 'emojibase');

const emoji = {
  hexcode: '1F600',
  emoji: '😀',
  label: 'grinning face',
  shortcodes: []
};

// Join shortcodes from multiple sources
const enrichedEmoji = joinShortcodesToEmoji(emoji, [githubCodes, emojibaseCodes]);

// Result:
// {
//   hexcode: '1F600',
//   emoji: '😀',
//   label: 'grinning face',
//   shortcodes: ['grinning', 'grinning_face']  // Combined and deduplicated
// }
```

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

### Import Versioned Unicode Data

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

Import emoji characters grouped by Unicode release versions from the emojibase-data package.

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

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

### joinShortcodes

Source: https://context7.com/milesj/emojibase/llms.txt

Like `joinShortcodesToEmoji` but operates on an entire array of emoji objects. Modifies the array in place and returns it.

```APIDOC
## joinShortcodes

### Description
Like `joinShortcodesToEmoji` but operates on an entire array of emoji objects. Modifies the array in place and returns it.

### Method
`joinShortcodes(emojis: Emoji[], shortcodes: Shortcode[][]): Emoji[]

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { joinShortcodes, fetchShortcodes } from 'emojibase';
import data from 'emojibase-data/en/data.json';

const githubCodes = await fetchShortcodes('en', 'github');
const cldrCodes = await fetchShortcodes('en', 'cldr');

// Join shortcodes to all emojis in the dataset
const emojisWithShortcodes = joinShortcodes(data, [githubCodes, cldrCodes]);

// All emojis now have combined shortcodes from both presets
console.log(emojisWithShortcodes[0].shortcodes);
// ['grinning', 'grinning_face']
```

### Response
#### Success Response (200)
- **Emoji[]** - The modified array of emoji objects, with shortcodes joined.

#### Response Example
```json
// Example for the first emoji in the array:
// emojisWithShortcodes[0].shortcodes might be ['grinning', 'grinning_face']
```
```

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

### Fetch Localized Emoji Messages

Source: https://context7.com/milesj/emojibase/llms.txt

Fetches localized messages for emoji groups, subgroups, and skin tones. Use this to build emoji pickers with translated category labels. Supports specifying a version.

```typescript
import { fetchMessages } from 'emojibase';

// Fetch Chinese translations for groups and metadata
const chineseMessages = await fetchMessages('zh');

// Fetch French messages with specific version
const frenchMessages = await fetchMessages('fr', { version: '15.0.0' });

// Result structure:
// {
//   groups: [
//     { key: 'smileys-emotion', message: 'smileys & emotion', order: 0 },
//     { key: 'people-body', message: 'people & body', order: 1 },
//     ...
//   ],
//   subgroups: [
//     { key: 'face-smiling', message: 'smiling', order: 0 },
//     ...
//   ],
//   skinTones: [
//     { key: 'light', message: 'light skin tone' },
//     { key: 'medium', message: 'medium skin tone' },
//     ...
//   ]
// }
```

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

### Update Group Key Constants

Source: https://github.com/milesj/emojibase/blob/master/docs/new-major-checklist.md

Update the GROUP_KEY_* constants in the specified file after generating new types.

```javascript
const GROUP_KEY_ ICONS = "icons";
const GROUP_KEY_SMILEYS_EMOTION = "smileys-emotion";
```

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

### Import Emojibase Messages Data

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

Import the messages data for a specific locale, such as English.

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

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

### stripHexcode

Source: https://context7.com/milesj/emojibase/llms.txt

Strips zero-width joiners (200D) and variation selectors (FE0E, FE0F) from a hexadecimal codepoint string. Useful for normalizing hexcodes for comparison.

```APIDOC
## stripHexcode

### Description
Strips zero-width joiners (200D) and variation selectors (FE0E, FE0F) from a hexadecimal codepoint string. Useful for normalizing hexcodes for comparison.

### Method
`stripHexcode`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **hexcode** (string) - Required - The hexadecimal codepoint string to strip.

### Request Example
```typescript
import { stripHexcode } from 'emojibase';

// Strip variation selector
stripHexcode('1F468-200D-2695-FE0F');

// Strip ZWJ from family emoji
stripHexcode('1F468-200D-1F469-200D-1F467-200D-1F466');

// Already stripped hexcode unchanged
stripHexcode('1F600');
```

### Response
#### Success Response (200)
- **strippedHexcode** (string) - The hexadecimal codepoint string with joiners and selectors removed.

#### Response Example
```json
"1F468-2695"
```
```