README

Unicode Emoji

Raw data for Unicode Emoji 🙂

The data are generated using the Unicode Emoji, Version 14.0 from Unicode.

You can learn more about emojis at Emojipedia or find some implementation details and trivia on the Wiki.

👉 Demo

Check the generated CSV file.

Or just take a look at what you can achieve using this package.

🔌 Installation

npm install unicode-emoji

🧰 Usage

This NPM package uses the ECMAScript Modules system, so the easiest way to use it, is with a Bundler (like WebPack), so you don't have to worry about how to make it available and import it.

With a Bundler

You can simply import it wherever you need it :

import * as unicodeEmoji from 'unicode-emoji';

With Node.js

ES Modules are only supported since Node.js v14.

Targeting CommonJS

When targeting CommonJS, you don't have access to static import, so you'll have to use dynamic import :

const unicodeEmoji = await import('unicode-emoji');

Also, you'll need to import it inside an async function, as top-level await is not supported for CommonJS.

Targeting ES Module

When setting "type": "module" inside your package.json or when importing it from a .mjs file, you can simply use the ES6 import syntax :

import * as unicodeEmoji from 'unicode-emoji';

From a web browser

If you are not using a bundler, you'll have to expose the unicode-emoji/index.js file so it is accessible from the web.

Using the full path

<script type="module">
  import * as unicodeEmoji from '/node_modules/unicode-emoji/index.js';
</script>

Using Import Maps

Import Maps can be very useful when you have several dependencies between different modules, as it allows you to import modules using their names instead of their full path.

But they are not implemented in any browser yet, so you'll have to use a polyfill :

<script async src="https://unpkg.com/es-module-shims@0.12.1/dist/es-module-shims.js"></script>
<script type="importmap-shim">
  {
    "imports": {
      "unicode-emoji": "/node_modules/unicode-emoji/index.js"
    }
  }
</script>
<script type="module-shim">
  import * as unicodeEmoji from 'unicode-emoji';
</script>

📚 Documentation

Retrieve emojis

unicodeEmoji.getEmojis();

[
  {
    "emoji": "😀", // Emoji without skin tone variation
    "description": "grinning face",
    "version": "1.0",
    "keywords": ["face", "grin", "grinning face"],
    "category": "face-emotion",
    "group": "smileys-emotion",
    "subgroup": "face-smiling"
  },
  {
    "emoji": "👋", // Emoji with skin tone variations
    "description": "waving hand",
    "version": "0.6",
    "keywords": ["hand", "wave", "waving"],
    "category": "face-emotion",
    "group": "people-body",
    "subgroup": "hand-fingers-open",
    "variations": [
      {
        "emoji": "👋🏻",
        "description": "waving hand: light skin tone",
        "version": "1.0"
      },
      {
        "emoji": "👋🏼",
        "description": "waving hand: medium-light skin tone",
        "version": "1.0"
      },
      // ...
    ]
  },
  // ...
]

Retrieve components

unicodeEmoji.getComponents();

{
  "skin-tone": [
    {
      "emoji": "🏻",
      "description": "light skin tone",
      "version": "1.0"
    },
    {
      "emoji": "🏼",
      "description": "medium-light skin tone",
      "version": "1.0"
    },
    // ...
  ],
  "hair-style": [
    {
      "emoji": "🦰",
      "description": "red hair",
      "version": "11.0"
    },
    {
      "emoji": "🦱",
      "description": "curly hair",
      "version": "11.0"
    },
    // ...
  ]
}

Grouping & filtering

You can group & filter emojis by category, group, subgroup or version

Here is an example :

grouped by category
without emojis from the flags category
without emojis from the 0.6 & 0.7 versions
without emojis from all versions above version 12.0 (does not exclude emojis from the version 12.0)

const groupBy = 'category';
const omitWhere = { versionAbove: '12.0', category: ['flags'], version: ['0.6', '0.7'] };

// Only omitting
unicodeEmoji.getEmojis(omitWhere);

// Only grouping
unicodeEmoji.getEmojisGroupedBy(groupBy);

// Grouping and omitting
unicodeEmoji.getEmojisGroupedBy(groupBy, omitWhere);

Keep in mind that :

const omitWhere = { versionAbove: '12.0' };

Is equivalent to :

const omitWhere = { version: ['12.1', '13.0', '13.1', '14.0'] };

But you should always use the first one, as it will be future-proof for when new versions of unicode-emoji are released.

So that updating your dependencies will not opt you into newer emojis that are not yet supported on every platforms.

📋 Details

While complete data are available on GitHub :

unicode-emoji.csv provides complete flat data
unicode-emoji.json provides complete hierarchical data

Only the stripped-down unicode-emoji.js file is bundled within the NPM package to greatly reduce its size

Usage no npm install needed!