emojidex-unicode

A Unicode-accurate emoji dataset and utility library built directly from the official
emoji-test.txt.

Designed for APIs and text tooling, with full metadata, fast search, and zero runtime dependencies.

✨ Features

• Official Unicode source (emoji-test.txt)
• Versioned Unicode support (17.0.0 → 18+)
• Full emoji metadata
• Prebuilt indexes for fast lookups
• Keyword & fuzzy search
• Emoji shortcodes (:smile:)
• Skin-tone helpers
• Group & subgroup filtering
• Random emoji helpers
• Dual ESM + CJS builds
• Zero runtime dependencies

📦 Installation

npm install emojidex-unicode
# or
bun add emojidex-unicode

📚 Dataset Structure

export type EmojiEntry = {
  emoji: string;
  name: string;
  codePoints: string[];
  status: "fully-qualified" | "minimally-qualified" | "unqualified";
  group: string;
  subgroup: string;
  keywords: string[];
  shortcode: string;
  supportsSkinTone: boolean;
};

🔍 Search

import { search } from "emojidex-unicode";

search("scientist");
search("smile face");

📂 Group & Subgroup Filtering

import { byGroup, bySubgroup, listGroups } from "emojidex-unicode";

listGroups();
byGroup("Smileys & Emotion");
bySubgroup("person-role");

🧾 Emoji Shortcodes

import { replaceShortcodes } from "emojidex-unicode";

replaceShortcodes("This is fire :fire:");

Output:

This is fire 🔥

🎨 Skin-Tone Helpers

import { withSkinTone, allSkinTones } from "emojidex-unicode";

withSkinTone("👍", 3);
allSkinTones("👋");

🎲 Random Emoji Utilities

import { randomEmoji, randomByGroup } from "emojidex-unicode";

randomEmoji();
randomByGroup("Animals & Nature");

ℹ Emoji Metadata Lookup

import { getEmojiInfo, findByName } from "emojidex-unicode";

getEmojiInfo("👨‍🔬");
findByName("GRINNING FACE");

🔄 Unicode Updates

// scripts/config.ts
export const UNICODE_VERSION = "17.0.0";

bun run update
bun run build

📄 Data Source

Emoji data derived from:

https://www.unicode.org/Public/17.0.0/emoji/emoji-test.txt

Copyright © Unicode Consortium.

📜 License

Emoji data is subject to the
https://www.unicode.org/license.html

Source code is MIT licensed.

🏁 Summary

emojidex-unicode provides a correct, fast, and future-proof emoji foundation for APIs and text tooling — built directly on official Unicode data.