emoji-picker-element

Native Emoji

By default, emoji-picker-element renders native emoji. It does not download large sprite sheets or fonts, which avoids IP issues and ensures emojis look consistent with the user's operating system. It is limited to the emoji font installed on the user's device.

Automatic Support Detection

The picker automatically detects emoji support. It will only render characters that the browser/OS can display to avoid showing empty boxes or broken characters. If no color emoji are supported, an error message is displayed.

IndexedDB Usage

To avoid keeping large JSON files (which can be ~850kB) in memory, the picker uses IndexedDB. This allows:

1. Avoiding constant re-parsing of JSON on every load.
2. Keeping the main thread free by allowing data to be loaded in a web worker if desired.

The emoji-picker-element is designed for client-side rendering only and does not support Server-Side Rendering (SSR). Attempting to import it on the server will result in a requestAnimationFrame is not defined error.

To use it in meta-frameworks, you must use client-side-only import techniques:

• Next.js: Use next/dynamic for dynamic imports.
• SvelteKit: Use onMount() to ensure code runs only on the client.
• General: Use dynamic import() to lazy-load the picker when a user interacts with a button.

By default, emoji-picker-element hides emojis that are not supported by the user's operating system or browser. To use a custom font and prevent the picker from hiding emojis, follow these steps:

1. Set the --emoji-font-family CSS property on the emoji-picker element.
2. Specify the maximum emoji version supported by your font using the emoji-version attribute (in HTML) or emojiVersion option (in JavaScript).

When emoji-version is set, the picker will not attempt to detect or hide unsupported emojis.

CSS Setup

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

HTML Usage

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

JavaScript Usage

const picker = new Picker({
  emojiVersion: 15.0
});

By default, the picker follows the user's system preference via prefers-color-scheme. You can override this behavior by adding the dark or light class directly to the <emoji-picker> element.

<emoji-picker class="dark"></emoji-picker>
<emoji-picker class="light"></emoji-picker>

The <emoji-picker> component has a default size, but you can control its dimensions using standard CSS. To make the picker fill its parent container, set both width and height to 100%.

emoji-picker {
  width: 100%;
  height: 100%;
}

To avoid side effects (like the Picker automatically registering itself as a custom element) and to allow bundlers like Webpack or Rollup to tree-shake effectively, import the modules from their specific entry points:

import Picker from 'emoji-picker-element/picker';
import Database from 'emoji-picker-element/database';

Since the component uses Shadow DOM, you cannot easily change its internal styles with arbitrary CSS. Instead, use the provided CSS variables to customize colors, sizes, and layout properties.

emoji-picker {
  --num-columns: 6;
  --emoji-size: 3rem;
  --background: gray;
}

You can use the Picker class to create an emoji picker instance. You can instantiate it via JavaScript and append it to the DOM, or use it as a declarative custom element in HTML.

JavaScript usage:

import { Picker } from 'emoji-picker-element';
const picker = new Picker();
document.body.appendChild(picker);

HTML usage:

<emoji-picker
  locale="fr"
  data-source="/fr-emoji.json"
  skin-tone-emoji="✌"
></emoji-picker>

Note: Complex properties like i18n or customEmoji cannot be set via HTML attributes because they require object types.

The component uses the :focus-visible pseudo-class for its accessibility focus ring. If you need to support browsers that do not natively support :focus-visible, you can use the focus-visible polyfill and apply it to the picker's shadowRoot.

import 'focus-visible';

const picker = new Picker();
applyFocusVisiblePolyfill(picker.shadowRoot);

Windows (specifically in Chromium-based browsers) lacks support for country flag emojis. To fix this, you can use the country-flag-emoji-polyfill package. This allows the picker to use a specific font for flags while falling back to native fonts for other emojis.

import { polyfillCountryFlagEmojis } from 'country-flag-emoji-polyfill';

// emoji-picker-element will use "Twemoji Mozilla" and fall back to other fonts for non-flag emoji
polyfillCountryFlagEmojis('Twemoji Mozilla');

To reduce external dependencies or host data on your own server, you can provide a custom URL to the dataSource option when initializing the Picker.

1. Install the data package: npm install emoji-picker-element-data@^1.
2. Host the JSON file (e.g., node_modules/emoji-picker-element-data/en/emojibase/data.json) on your web server.
3. Pass the path to the Picker constructor.

Note on CORS: If the JSON file is hosted on a different domain than the picker, the server must expose Access-Control-Allow-Origin: * and Access-Control-Expose-Headers: ETag (or *) to allow the picker to function correctly and use caching.

const picker = new Picker({
  dataSource: '/path/to/my/webserver/data.json'
});