emoji-data: a JSON file and spritesheets for every emoji, from four vendors

One JSON array that answers the questions a picker needs

The central artifact is emoji.json, an array of entries, and the design goal is that a program should not have to know anything about Unicode to use it. The README describes the project as easy-to-parse data about emoji along with spritesheet-style images for use on the web, and the fields reflect that.

A single entry carries more than the codepoint. It has the official Unicode name in uppercase, the unified codepoint as 4 to 5 hex digits, the image filename, the sprite coordinates on the sheet, one or more short names, category and subcategory names, a global sort order, and the emoji version it was added in. For emoji with skin tones it carries a nested map of variations keyed by modifier codepoint, and for emoji that were replaced it carries obsoletes and obsoleted_by pointers.

Two fields do the quiet work of making this usable in a real product. `short_name` is described as the commonly-agreed short name as supported in Campfire and GitHub via colon syntax, and `short_names` is an array of all known short names. That means `:point_up:` works as a lookup key without you maintaining a name registry, which is the piece most emoji projects skip.

The vendor codepoint fields are the other reason to use this rather than deriving everything yourself. `docomo`, `au`, `softbank` and `google` hold the legacy Unicode codepoints used by various mobile vendors, and `non_qualified` holds the version without a variation selector where one exists. Anyone who has ever had an emoji fail to render on an older carrier-era handset knows what that column is for.

Installing only the spritesheets you need

The git repository is described as pretty big, almost 10GB, because it contains every image set at every size. The npm route avoids that. The base package installs only the 32px full-fidelity spritesheets with fallback images:

npm install emoji-datasource

Anything else requires additional modules, and the README enumerates them by vendor:

npm install emoji-datasource-apple
npm install emoji-datasource-google
npm install emoji-datasource-twitter
npm install emoji-datasource-facebook

The split is deliberate rather than incidental. The base package covers what most projects need, and the vendor packages exist because the images come from four sources with different licensing, different quality and wildly different repository weight. If you only need Apple artwork, installing all four is dead weight on your registry mirror.

There is also a CDN option. The README says you can use it without downloading via the jsDelivr CDN, with different sizes available under a query for emoji-datasource by author iamcal. That is worth knowing for a static site where pulling a 10GB git clone into your build is not realistic.

One documentation note. The npm install command for the base package appears in the README as indented text rather than inside a fence, while the vendor packages are in a proper fenced block. Same command, different markup, no difference to a person reading it, but worth knowing if you script-extract commands from documentation.

Sprite coordinates and the one pixel border rule

The spritesheet layout has one rule you have to know before doing any math: every emoji image in the sheet has a 1 pixel transparent border around it. So the 64px sheet is made up of 66px squares and the 16px sheet of 18px squares. The README gives the coordinate formulas directly:

x = (sheet_x * (sheet_size + 2)) + 1; y = (sheet_y * (sheet_size + 2)) + 1;

Those two lines are why `sheet_x` and `sheet_y` in the JSON are safe to use without any further lookup. The plus one is the border, the plus two is the border counted on both sides of a cell.

The tree shows how many sheets exist. There are four vendor families in the root: `sheet_apple_16` through `sheet_apple_64`, `sheet_facebook_16` through `sheet_facebook_64`, `sheet_google_16` through `sheet_google_64` and `sheet_twitter_16` through `sheet_twitter_32`. Alongside them are `img-apple-160`, `img-apple-64`, `img-facebook-64`, `img-facebook-96`, `img-google-136`, `img-google-64`, `img-twitter-64` and `img-twitter-72`, which are individual image directories rather than sheets.

Three additional directories modify the sheets rather than adding sizes. `sheets-indexed-128` and `sheets-indexed-256` hold sheets with indexed color palettes of 128 and 256 colors, which the README says makes the image much smaller at the cost of a lot of quality. `sheets-clean` holds sheets with no fallbacks. The naming convention maps cleanly between git and npm, so `/sheets-clean/sheet_apple_16_clean.png` becomes `/img/apple/sheets-clean/16.png` in the package.

Fallback sheets versus clean sheets, and why it is a rights question

This is the part of the design that is easy to miss and expensive to get wrong, because it is not only a rendering decision.

The default sheets are 24 bit color and include fallbacks, meaning that if the preferred vendor set has no image for a given emoji, the sheet substitutes an image from another vendor. The result looks complete. The 128 and 256 color indexed sheets are also fallback sheets, so they look complete too, just at lower quality.

The clean sheets are the exception. The README states they do not contain fallbacks for missing images, so the Google sheet only contains Google images and no Apple fallbacks. The consequence is that some images are replaced with the fallback character, a question mark. In exchange, the README says the usage rights are simpler, and that is the trade. A sheet that quietly mixes four vendors' artwork into one file is a sheet whose licensing you have to reason about per emoji, and a clean sheet drawn from one source is a single question you can answer once.

If you are building something commercial, that distinction is the reason to know this project exists in the shape it does. It is also why the vendor packages are split out rather than bundled, since combining vendor sets is your decision to make, not the package's.

Data versioning, the catalog, and what the repository does not do

Two things about versioning deserve attention. The README states the current version supports Emoji version 17.0, dated September 2025, while package.json declares version 16.0.0. Those are different axes: one is the package release, the other is the Unicode emoji version the data covers. If you are pinning, pin deliberately and know which one you are tracking.

The GitHub releases list is empty. There are no tagged releases in the repository, and the version history lives in a file, CHANGES.md, which the README links as the place to look. For a data set that people vendor into builds, that is a mild ergonomic gap: you cannot point at a tag to say which commit you took. The repository has 32 open issues and the last push was on 2026-09-14.

For browsing rather than consuming, there is a catalog at table.htm, linked from the README, and categories.json plus emoji_pretty.json sit alongside emoji.json in the tree. emoji_pretty.json is the human-oriented variant, which is a small courtesy that says the author thought about inspection as well as integration.

The notable omission is rendering. There is no JavaScript picker, no component library and no font work here. This is a data project that also happens to produce images, and the word data in the package description is accurate. If you want an emoji picker with search and categories, you will pair this with something else, and the value it adds is that your picker's artwork and your short-name lookups come from a single consistent source with known coordinates.

Editorial conclusion

emoji-data is the right pick when you are rendering emoji yourself and need to know not just what an emoji is called but where its pixels live, which vendor's artwork you have, and which Unicode version introduced it. The short-name support, with names matching what GitHub and Campfire accept in colon syntax, means it slots into existing text without a lookup layer. What it does not do is render: there is no component, no CSS helper and no fallback chain logic, so a text input still needs a picker and a substitution step that this project leaves to you. Verify two things before depending on it. The package version and the data version are separate axes, since package.json reads 16.0.0 while the README states support for Emoji version 17.0 from September 2025, so check which data you actually get rather than reading the version string as a data version. Second, the clean sheets are the ones with simpler usage rights, because they contain no vendor fallback images and therefore render a question mark where a set is missing, while the fallback sheets are the ones that look complete. Decide which trade you want before you wire it into a product, and read CHANGES.md, which is where the project's version history lives.

Frequently asked questions

Official sources

1. iamcal/emoji-data on GitHub
2. Issues
3. License: MIT
4. README