emoji-picker-element for a lightweight browser emoji picker

The emoji-selection problem addressed by emoji-picker-element

emoji-picker-element addresses the work required to place a complete emoji picker in a web interface. A usable picker needs more than a grid of characters. It needs search, categories, skin tone selection, selection events, emoji metadata, and storage for application state such as favorites and preferred skin tone. The project packages those responsibilities as a web component rather than an interface tied to React, Vue, Svelte, or another framework.

The intended users are developers adding emoji input to messaging, publishing, commenting, or content-editing products. The README says the component requires no framework or bundler. A page can load one ES module and add `<emoji-picker>` to its HTML. Applications built with a framework can still render the custom element and listen for its browser events.

The catalog supports Emoji v17.0, although the README warns that visible support depends on the operating system. Custom emoji are also supported. That makes the project relevant to products with branded reaction sets in addition to Unicode emoji. The database interface exposes search, shortcode lookup, Unicode or name lookup, group lookup, favorites, and preferred skin tone operations, so an application can use the data layer without exposing the full picker interface.

How the Picker, Database, and IndexedDB layers divide work

The repository exposes separate artifacts for the interface and data layer. `picker.js` contains the picker artifact, while `database.js` represents the emoji database. Both have matching TypeScript declaration files. The documented Database API includes constructors, a `customEmoji` accessor, readiness handling, search, lookup, favorites, and skin tone preferences. This separation lets an application choose between adding the complete visual component and importing the database functionality it needs.

IndexedDB is the documented persistence mechanism. The README describes the project as memory efficient because it uses IndexedDB rather than keeping the entire emoji dataset continuously in memory. Its data and offline sections discuss JSON loading, cache performance, shortcodes, environments without IndexedDB, and offline-first operation. These choices make data loading and retention part of the component's operating model rather than details left entirely to the application.

The selection event carries structured information. The README example includes an `emoji` object with fields such as `annotation`, `group`, `order`, `shortcodes`, `tags`, `unicode`, and `version`. The event detail also contains the selected `unicode` and numeric `skinTone`. An editor can insert `event.detail.unicode` while using the metadata for validation, moderation, analytics, or indexing.

The repository also includes tree-shaking documentation. An application that needs only database operations does not automatically have to import the visible picker. That distinction can matter in sites with strict JavaScript budgets, although the README's approximate bundle figure describes the package rather than the size of every possible integration.

Installing the component and handling its first selection

For an npm-based project, the README specifies the following package installation and module import. Importing the package registers the custom element so the browser recognizes `<emoji-picker>`.

npm install emoji-picker-element

import 'emoji-picker-element';

Add the element to the page and listen for its documented selection event:

<emoji-picker></emoji-picker>

The following handler logs the complete event detail. In an editor, the application can use the `unicode` field when its destination accepts the selected character directly.

document.querySelector('emoji-picker')
  .addEventListener('emoji-click', event => console.log(event.detail));

A page that does not use npm can load the module through the CDN URL documented in the README:

<script type="module" src="https://cdn.jsdelivr.net/npm/emoji-picker-element@^1/index.js"></script>

The CDN expression targets the documented major release stream. The repository has no GitHub releases, while `package.json` identifies version `1.29.1`. A production application should lock the package version it tests instead of leaving the documented `^1` CDN expression to resolve differently over time.

Native rendering, custom fonts, and platform-specific emoji

By default, emoji-picker-element renders native emoji and hides unsupported entries. The README explains that emoji support varies across browsers and operating systems. This prevents unsupported characters from appearing as empty boxes in the default picker, but it also means the visible catalog and artwork can differ between clients.

Applications that supply a custom font can set `--emoji-font-family` and declare the maximum emoji version supported by that font:

emoji-picker {
 --emoji-font-family: MyCustomFont;
}

<emoji-picker emoji-version="15.0"></emoji-picker>

The JavaScript option uses `emojiVersion`:

When `emoji-version` or `emojiVersion` is set, the component does not attempt to detect unsupported emoji or hide entries. The README warns that color font support varies across browsers and operating systems, and that some browsers have rendering defects or may not render the font. An incorrect version declaration can therefore expose entries the selected font cannot render correctly.

Native rendering is therefore the simpler default, not a guarantee of uniform appearance. A product that needs controlled artwork must manage the custom font, test browser support, and ensure its declared emoji version matches the font. The README also describes a separate fallback for missing flag emoji on Windows, but that fallback addresses a specific platform gap rather than every difference in emoji presentation.

Search, favorites, skin tone, and custom emoji data

The database API provides documented methods for several non-visual workflows. `getEmojiBySearchQuery` supports search, while `getEmojiByShortcode`, `getEmojiByUnicodeOrName`, and `getEmojiByGroup` support structured lookup. Returned records include shortcodes, tags, annotations, group and order values, Unicode text, and the Emoji version. An application could validate a submitted shortcode or Unicode character before storing user input.

Favorites and skin tone preferences also have explicit API operations. `incrementFavoriteEmojiCount`, `getTopFavoriteEmoji`, `setPreferredSkinTone`, and `getPreferredSkinTone` expose storage-related behavior. Applications can use those methods when ranking or personalization must extend beyond the default interface. They must still account for browsers or privacy configurations where IndexedDB access is unavailable.

Custom emoji are part of the catalog rather than only font substitutions. The JavaScript API includes a `customEmoji` accessor and separate custom emoji documentation. Implementers should consult the custom emoji API section for the exact registration format and record payload. Implementers should use the repository's custom emoji API section for the exact format and conversion behavior.

Internationalization is supported through built-in translations, and the picker can use a custom category order. The package publishes `/i18n/*`, while its build scripts generate internationalization files and documentation. A localized application therefore has two distinct concerns: category labels and ordering inside the component, and interpretation of selected Unicode or custom emoji records in application code.

Operational limits, maintenance, and upgrade work

The clearest failure mode is loss of IndexedDB access. The README has a dedicated section for environments without IndexedDB, but it does not promise that every persistence function behaves identically when storage is blocked. Browser privacy settings, embedded webviews, storage policies, and organizational browser configuration can affect availability. An editor should test persistence in each supported client environment instead of assuming that desktop-browser behavior applies everywhere.

Visual consistency is another boundary. Supported native emoji can still look different across operating systems. Hiding unsupported emoji cleans up the default catalog but does not create a single controlled artwork set. The custom font route transfers font loading, version declaration, and browser testing to the application. It is unsuitable when the product demands predictable glyphs but cannot maintain that testing.

emoji-picker-element is also a browser component, not documentation for integrating an operating-system mobile keyboard. Its IndexedDB storage, custom element boundary, events, and database methods describe client-side web behavior. A native mobile application requiring operating-system keyboard services would need a different integration model.

The repository is not archived, and its last push was on 2026-06-08. It has no GitHub releases. `package.json` identifies `1.29.1`, and the repository includes `CHANGELOG.md`, so an upgrade review should compare that changelog with the version selected by the package manager or CDN configuration. A repository push alone does not define the application's dependency version.

The package uses Apache-2.0. Teams redistributing source or built copies should retain the applicable license text and notices and review their distribution for other obligations. This identifies the license boundary without replacing legal review.

Editorial conclusion

Adopt emoji-picker-element when a web application can use native emoji rendering, a custom element, and IndexedDB-backed state. Do not choose it when identical emoji artwork across operating systems is mandatory or when persistent browser storage is prohibited. Before integration, verify the documented events, custom emoji registration, supported browser behavior, offline storage path, and the selected package version.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. nolanlawson/emoji-picker-element on GitHub
4. Project website
5. README