{"id":13805026,"url":"https://github.com/nolanlawson/emoji-picker-element","last_synced_at":"2025-05-13T16:10:52.076Z","repository":{"id":37372136,"uuid":"261938369","full_name":"nolanlawson/emoji-picker-element","owner":"nolanlawson","description":"A lightweight emoji picker for the modern web","archived":false,"fork":false,"pushed_at":"2025-04-12T17:17:09.000Z","size":6362,"stargazers_count":1598,"open_issues_count":30,"forks_count":92,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-10T13:01:51.340Z","etag":null,"topics":["custom-elements","emoji","emoji-picker","indexeddb","web-components"],"latest_commit_sha":null,"homepage":"https://nolanlawson.github.io/emoji-picker-element/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nolanlawson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-07T03:17:18.000Z","updated_at":"2025-05-09T16:32:16.000Z","dependencies_parsed_at":"2024-04-13T03:21:26.443Z","dependency_job_id":"6ebafacc-24ca-406b-bffd-acb95e587de8","html_url":"https://github.com/nolanlawson/emoji-picker-element","commit_stats":{"total_commits":691,"total_committers":14,"mean_commits":"49.357142857142854","dds":0.08538350217076696,"last_synced_commit":"e88749a52f288394b371e2c789b90dd9485083cd"},"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolanlawson%2Femoji-picker-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolanlawson%2Femoji-picker-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolanlawson%2Femoji-picker-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolanlawson%2Femoji-picker-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nolanlawson","download_url":"https://codeload.github.com/nolanlawson/emoji-picker-element/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253518960,"owners_count":21921082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-elements","emoji","emoji-picker","indexeddb","web-components"],"created_at":"2024-08-04T01:00:56.481Z","updated_at":"2025-05-13T16:10:47.036Z","avatar_url":"https://github.com/nolanlawson.png","language":"JavaScript","funding_links":[],"categories":["Real World","JavaScript"],"sub_categories":["Components"],"readme":"emoji-picker-element\n====\n\n![Screenshot of emoji-picker-element in light and dark modes](https://nolanwlawson.files.wordpress.com/2020/06/out.png)\n\n```html\n\u003cemoji-picker\u003e\u003c/emoji-picker\u003e\n```\n\nA lightweight emoji picker, distributed as a web component.\n\n**Features:**\n\n- Supports [Emoji v16.0](https://emojipedia.org/emoji-16.0) (depending on OS) and custom emoji\n- Uses IndexedDB, so it consumes [far less memory](https://nolanlawson.com/2020/06/28/introducing-emoji-picker-element-a-memory-efficient-emoji-picker-for-the-web/) than other emoji pickers\n- [Small bundle size](https://bundlephobia.com/result?p=emoji-picker-element) (~12.5kB min+gz)\n- Renders native emoji by default, with support for custom fonts\n- [Accessible by default](https://nolanlawson.com/2020/07/01/building-an-accessible-emoji-picker/)\n- Framework and bundler not required, just add a `\u003cscript\u003e` tag and use it\n\n**Table of contents:**\n\n\u003c!-- toc start --\u003e\n\n- [emoji-picker-element](#emoji-picker-element-)\n * [Usage](#usage)\n + [Examples](#examples)\n + [Emoji support](#emoji-support)\n - [Custom emoji font](#custom-emoji-font)\n - [Polyfilling flag emoji on Windows](#polyfilling-flag-emoji-on-windows)\n * [Styling](#styling)\n + [Size](#size)\n + [Dark mode](#dark-mode)\n + [CSS variables](#css-variables)\n + [Focus outline](#focus-outline)\n + [Small screen sizes](#small-screen-sizes)\n + [Custom styling](#custom-styling)\n * [JavaScript API](#javascript-api)\n + [Picker](#picker)\n - [Events](#events)\n * [`emoji-click`](#emoji-click)\n * [`skin-tone-change`](#skin-tone-change)\n - [Internationalization](#internationalization)\n * [Built-in translations](#built-in-translations)\n - [Custom category order](#custom-category-order)\n + [Database](#database)\n - [Constructors](#constructors)\n * [constructor](#constructor)\n - [Accessors](#accessors)\n * [customEmoji](#customemoji)\n - [Methods](#methods)\n * [close](#close)\n * [delete](#delete)\n * [getEmojiByGroup](#getemojibygroup)\n * [getEmojiBySearchQuery](#getemojibysearchquery)\n * [getEmojiByShortcode](#getemojibyshortcode)\n * [getEmojiByUnicodeOrName](#getemojibyunicodeorname)\n * [getPreferredSkinTone](#getpreferredskintone)\n * [getTopFavoriteEmoji](#gettopfavoriteemoji)\n * [incrementFavoriteEmojiCount](#incrementfavoriteemojicount)\n * [ready](#ready)\n * [setPreferredSkinTone](#setpreferredskintone)\n + [Custom emoji](#custom-emoji)\n + [Tree-shaking](#tree-shaking)\n + [Within a meta-framework (Next.js, SvelteKit, etc.)](#within-a-meta-framework-nextjs-sveltekit-etc)\n + [Within a Svelte project](#within-a-svelte-project)\n * [Data and offline](#data-and-offline)\n + [Data source and JSON format](#data-source-and-json-format)\n + [Shortcodes](#shortcodes)\n + [Cache performance](#cache-performance)\n + [emojibase-data compatibility (deprecated)](#emojibase-data-compatibility-deprecated)\n + [Trimming the emoji data (deprecated)](#trimming-the-emoji-data-deprecated)\n + [Offline-first](#offline-first)\n + [Environments without IndexedDB](#environments-without-indexeddb)\n * [Design decisions](#design-decisions)\n + [IndexedDB](#indexeddb)\n + [Native emoji](#native-emoji)\n + [JSON loading](#json-loading)\n + [Browser support](#browser-support)\n * [Contributing](#contributing)\n\n\u003c!-- toc end --\u003e\n\n## Usage\n\nVia npm:\n\n npm install emoji-picker-element\n\n```js\nimport 'emoji-picker-element';\n```\n\nOr as a `\u003cscript\u003e` tag:\n\n```html\n\u003cscript type=\"module\" src=\"https://cdn.jsdelivr.net/npm/emoji-picker-element@^1/index.js\"\u003e\u003c/script\u003e\n```\n\nThen use the HTML:\n\n```html\n\u003cemoji-picker\u003e\u003c/emoji-picker\u003e\n```\n\nAnd listen for `emoji-click` events:\n\n```js\ndocument.querySelector('emoji-picker')\n .addEventListener('emoji-click', event =\u003e console.log(event.detail));\n```\n\nThis will log:\n\n```json\n{\n \"emoji\": {\n \"annotation\": \"grinning face\",\n \"group\": 0,\n \"order\": 1,\n \"shortcodes\": [ \"grinning_face\", \"grinning\" ],\n \"tags\": [ \"face\", \"grin\" ],\n \"unicode\": \"šŸ˜€\",\n \"version\": 1,\n \"emoticon\": \":D\"\n },\n \"skinTone\": 0,\n \"unicode\": \"šŸ˜€\"\n}\n```\n\n### Examples\n\n- [Demo](https://nolanlawson.github.io/emoji-picker-element) ([source](https://github.com/nolanlawson/emoji-picker-element/blob/master/docs/index.html))\n- [Button with tooltip/popover](https://nolanlawson.github.io/emoji-picker-element/demos/tooltip/index.html) ([source](https://github.com/nolanlawson/emoji-picker-element/blob/master/docs/demos/tooltip/index.html))\n- [Inserting emoji into a text input](https://nolanlawson.github.io/emoji-picker-element/demos/input/index.html) ([source](https://github.com/nolanlawson/emoji-picker-element/blob/master/docs/demos/input/index.html))\n- [In a React app](https://nolanlawson.github.io/emoji-picker-element/demos/react/index.html) ([source](https://github.com/nolanlawson/emoji-picker-element/blob/master/docs/demos/react/index.html))\n- [Custom emoji font](https://nolanlawson.github.io/emoji-picker-element/demos/custom-font/index.html) ([source](https://github.com/nolanlawson/emoji-picker-element/blob/master/docs/demos/custom-font/index.html))\n- [Fallback for missing flag emoji on Windows](https://nolanlawson.github.io/emoji-picker-element/demos/flags/index.html) ([source](https://github.com/nolanlawson/emoji-picker-element/blob/master/docs/demos/flags/index.html))\n\n### Emoji support\n\n[Emoji support varies](https://nolanlawson.com/2022/04/08/the-struggle-of-using-native-emoji-on-the-web/) across browsers and operating systems. By default, `emoji-picker-element` will hide unsupported emoji from the picker.\n\nTo work around this, you can use [a custom emoji font](#custom-emoji-font) or [polyfill flag emoji on Windows](#polyfilling-flag-emoji-on-windows).\n\n#### Custom emoji font\n\nTo use a custom emoji font, first set the `--emoji-font-family` CSS property:\n\n```css\nemoji-picker {\n --emoji-font-family: MyCustomFont;\n}\n```\n\nThen, specify the maximum emoji version supported by the font. (See [Emojipedia](https://emojipedia.org/emoji-versions/) for a list of versions.)\n\nIn HTML:\n\n```html\n\u003cemoji-picker emoji-version=\"15.0\"\u003e\u003c/emoji-picker\u003e\n```\n\nOr JavaScript:\n\n```js\nconst picker = new Picker({\n emojiVersion: 15.0\n});\n```\n\nIf the `emoji-version`/`emojiVersion` option is set, then `emoji-picker-element` will not attempt to detect unsupported emoji or hide them.\n\nAlso note that support for color fonts [varies across browsers and OSes](https://caniuse.com/colr), and some browsers may have \u003ca href=\"https://github.com/nolanlawson/emoji-picker-element/pull/308#issuecomment-1367491149\"\u003ebugs\u003c/a\u003e or not render the font at all. Be careful to test your supported browsers when using this approach.\n\n#### Polyfilling flag emoji on Windows\n\nAs of this writing, [Windows does not support country flag emoji](https://answers.microsoft.com/en-us/windows/forum/all/where-are-the-flag-emoji-in-windows-10/93daa6e8-880a-48b1-9891-ab5bfbfbce98). This is only a problem in Chromium-based browsers, because Firefox ships with its own emoji font.\n\nTo work around this, you can use [country-flag-emoji-polyfill](https://www.npmjs.com/package/country-flag-emoji-polyfill):\n\n```js\nimport { polyfillCountryFlagEmojis } from 'country-flag-emoji-polyfill';\n\n// emoji-picker-element will use \"Twemoji Mozilla\" and fall back to other fonts for non-flag emoji\npolyfillCountryFlagEmojis('Twemoji Mozilla');\n```\n\nNote that you do not need to do this if you are using [a custom emoji font](#custom-emoji-font).\n\n## Styling\n\n`emoji-picker-element` uses [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM), so its inner styling cannot be (easily) changed with arbitrary CSS. Refer to the API below for style customization.\n\n### Size\n\n`emoji-picker-element` has a default size, but you can change it to whatever you want:\n\n```css\nemoji-picker {\n width: 400px;\n height: 300px;\n}\n```\n\nFor instance, to make it expand to fit whatever container you give it:\n\n```css\nemoji-picker {\n width: 100%;\n height: 100%;\n}\n```\n\n### Dark mode\n\nBy default, `emoji-picker-element` will automatically switch to dark mode based on \n[`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). \nOr you can add the class `dark` or `light` to force dark/light mode:\n\n```html\n\u003cemoji-picker class=\"dark\"\u003e\u003c/emoji-picker\u003e\n\u003cemoji-picker class=\"light\"\u003e\u003c/emoji-picker\u003e\n```\n\n### CSS variables\n\nMost colors and sizes can be styled with CSS variables. For example:\n\n```css\nemoji-picker {\n --num-columns: 6;\n --emoji-size: 3rem;\n --background: gray;\n}\n```\n\nHere is a full list of options:\n\n\u003c!-- CSS variable options start --\u003e\n\n| Variable | Default | Default (dark) | Description |\n| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- |\n| `--background` | `#fff` | `#222` | Background of the entire `\u003cemoji-picker\u003e` |\n| `--border-color` | `#e0e0e0` | `#444` | |\n| `--border-radius` | `0` | | Border radius of the entire picker |\n| `--border-size` | `1px` | | Width of border used in most of the picker |\n| `--button-active-background` | `#e6e6e6` | `#555555` | Background of an active button |\n| `--button-hover-background` | `#d9d9d9` | `#484848` | Background of a hovered button |\n| `--category-emoji-padding` | `var(--emoji-padding)` | | Vertical/horizontal padding on category emoji, if you want it to be different from `--emoji-padding` |\n| `--category-emoji-size` | `var(--emoji-size)` | | Width/height of category emoji, if you want it to be different from `--emoji-size` |\n| `--category-font-color` | `#111` | `#efefef` | Font color of custom emoji category headings |\n| `--category-font-size` | `1rem` | | Font size of custom emoji category headings |\n| `--emoji-font-family` | `\"Twemoji Mozilla\",\"Apple Color Emoji\",\"Segoe UI Emoji\",\"Segoe UI Symbol\",\"Noto Color Emoji\",\"EmojiOne Color\",\"Android Emoji\",sans-serif` | | Font family for a custom emoji font (as opposed to native emoji) |\n| `--emoji-padding` | `0.5rem` | | Vertical and horizontal padding on emoji |\n| `--emoji-size` | `1.375rem` | | Width and height of all emoji |\n| `--indicator-color` | `#385ac1` | `#5373ec` | Color of the nav indicator |\n| `--indicator-height` | `3px` | | Height of the nav indicator |\n| `--input-border-color` | `#999` | `#ccc` | |\n| `--input-border-radius` | `0.5rem` | | |\n| `--input-border-size` | `1px` | | |\n| `--input-font-color` | `#111` | `#efefef` | |\n| `--input-font-size` | `1rem` | | |\n| `--input-line-height` | `1.5` | | |\n| `--input-padding` | `0.25rem` | | |\n| `--input-placeholder-color` | `#999` | `#ccc` | |\n| `--num-columns` | `8` | | How many columns to display in the emoji grid |\n| `--outline-color` | `#999` | `#fff` | Focus outline color |\n| `--outline-size` | `2px` | | Focus outline width |\n| `--skintone-border-radius` | `1rem` | | Border radius of the skintone dropdown |\n\n\u003c!-- CSS variable options end --\u003e\n\n### Focus outline\n\nFor accessibility reasons, `emoji-picker-element` displays a prominent focus ring for keyboard users. This uses [`:focus-visible`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible) under the hood. To properly support [browsers that do not support `:focus-visible`](https://caniuse.com/css-focus-visible), you can use the [focus-visible](https://github.com/WICG/focus-visible) polyfill, e.g.:\n\n```js\nimport 'focus-visible';\n\nconst picker = new Picker();\napplyFocusVisiblePolyfill(picker.shadowRoot);\n```\n\n`emoji-picker-element` already ships with the proper CSS for both the `:focus-visible` standard and the polyfill.\n\n### Small screen sizes\n\nFor small screen sizes, you should probably add some CSS like the following:\n\n```css\n@media screen and (max-width: 320px) {\n emoji-picker {\n --num-columns: 6;\n --category-emoji-size: 1.125rem;\n }\n}\n```\n\n`emoji-picker-element` does not ship with any CSS to explicitly handle small screen sizes. The right CSS depends on which screen sizes your app supports, and the size of the picker within your app. Perhaps in the future [container queries](https://caniuse.com/css-container-queries) can solve this problem.\n\n### Custom styling\n\nIf you absolutely must go beyond the styling API above, you can do something like this:\n\n```js\nconst style = document.createElement('style');\nstyle.textContent = `/* custom shadow dom styles here */`\npicker.shadowRoot.appendChild(style);\n```\n\n## JavaScript API\n\n### Picker\n\nBasic usage:\n\n```js\nimport { Picker } from 'emoji-picker-element';\nconst picker = new Picker();\ndocument.body.appendChild(picker);\n```\n\nThe `new Picker(options)` constructor supports several options:\n\n| Name | Type | Default | Description |\n|-------------------------|---------------|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|\n| `customCategorySorting` | function | - | Function to sort custom category strings (sorted alphabetically by default) |\n| `customEmoji` | CustomEmoji[] | - | Array of custom emoji |\n| `dataSource` | string | \"https://cdn.jsdelivr.net/npm/emoji-picker-element-data@^1/en/emojibase/data.json\" | URL to fetch the emoji data from (`data-source` when used as an attribute) |\n| `emojiVersion` | number | - | Maximum supported emoji version as a number (e.g. `14.0` or `13.1`). Setting this disables the default emoji support detection. |\n| `i18n` | I18n | - | i18n object (see below for details) |\n| `locale` | string | \"en\" | Locale string |\n| `skinToneEmoji` | string | \"šŸ–ļø\" | The emoji to use for the skin tone picker (`skin-tone-emoji` when used as an attribute) |\n\n\n\nFor instance:\n\n```js\nconst picker = new Picker({\n locale: 'fr',\n dataSource: '/fr-emoji.json'\n})\n```\n\nThese values can also be set at runtime:\n\n```js\nconst picker = new Picker();\npicker.dataSource = '/my-emoji.json';\n```\n\nSome values can also be set as declarative attributes:\n\n```html\n\u003cemoji-picker\n locale=\"fr\"\n data-source=\"/fr-emoji.json\"\n skin-tone-emoji=\"āœŒ\"\n\u003e\u003c/emoji-picker\u003e\n```\n\nNote that complex properties like `i18n` or `customEmoji` are not supported as attributes, because the DOM only\nsupports string attributes, not complex objects.\n\n#### Events\n\n##### `emoji-click`\n\nThe `emoji-click` event is fired when an emoji is selected by the user. Example format:\n\n```javascript\n{\n emoji: {\n annotation: 'thumbs up',\n group: 1,\n order: 280,\n shortcodes: ['thumbsup', '+1', 'yes'],\n tags: ['+1', 'hand', 'thumb', 'up'],\n unicode: 'šŸ‘ļø',\n version: 0.6,\n skins: [\n { tone: 1, unicode: 'šŸ‘šŸ»', version: 1 },\n { tone: 2, unicode: 'šŸ‘šŸ¼', version: 1 },\n { tone: 3, unicode: 'šŸ‘šŸ½', version: 1 },\n { tone: 4, unicode: 'šŸ‘šŸ¾', version: 1 },\n { tone: 5, unicode: 'šŸ‘šŸæ', version: 1 }\n ]\n },\n skinTone: 4,\n unicode: 'šŸ‘šŸ¾'\n}\n```\n\nAnd usage:\n\n```js\npicker.addEventListener('emoji-click', event =\u003e {\n console.log(event.detail); // will log something like the above\n});\n```\n\nNote that `unicode` will represent whatever the emoji should look like\nwith the given `skinTone`. If the `skinTone` is 0, or if the emoji has\nno skin tones, then no skin tone is applied to `unicode`.\n\n##### `skin-tone-change`\n\nThis event is fired whenever the user selects a new skin tone. Example format:\n\n```js\n{\n skinTone: 5\n}\n```\n\nAnd usage:\n\n```js\npicker.addEventListener('skin-tone-change', event =\u003e {\n console.log(event.detail); // will log something like the above\n})\n```\n\nNote that skin tones are an integer from 0 (default) to 1 (light) through 5 (dark).\n\n#### Internationalization\n\nThe `i18n` parameter specifies translations for the picker interface. Here is the default English `i18n` object:\n\n\u003c!-- i18n options start --\u003e\n\n```json\n{\n \"categories\": {\n \"custom\": \"Custom\",\n \"smileys-emotion\": \"Smileys and emoticons\",\n \"people-body\": \"People and body\",\n \"animals-nature\": \"Animals and nature\",\n \"food-drink\": \"Food and drink\",\n \"travel-places\": \"Travel and places\",\n \"activities\": \"Activities\",\n \"objects\": \"Objects\",\n \"symbols\": \"Symbols\",\n \"flags\": \"Flags\"\n },\n \"categoriesLabel\": \"Categories\",\n \"emojiUnsupportedMessage\": \"Your browser does not support color emoji.\",\n \"favoritesLabel\": \"Favorites\",\n \"loadingMessage\": \"Loadingā€¦\",\n \"networkErrorMessage\": \"Could not load emoji.\",\n \"regionLabel\": \"Emoji picker\",\n \"searchDescription\": \"When search results are available, press up or down to select and enter to choose.\",\n \"searchLabel\": \"Search\",\n \"searchResultsLabel\": \"Search results\",\n \"skinToneDescription\": \"When expanded, press up or down to select and enter to choose.\",\n \"skinToneLabel\": \"Choose a skin tone (currently {skinTone})\",\n \"skinTones\": [\n \"Default\",\n \"Light\",\n \"Medium-Light\",\n \"Medium\",\n \"Medium-Dark\",\n \"Dark\"\n ],\n \"skinTonesLabel\": \"Skin tones\"\n}\n```\n\n\u003c!-- i18n options end --\u003e\n\nNote that some of these strings are only visible to users of screen readers. They are still important for accessibility!\n\n##### Built-in translations\n\nCommunity-provided translations for some languages [are available](https://github.com/nolanlawson/emoji-picker-element/tree/master/src/picker/i18n). You can use them like so:\n\n```js\nimport fr from 'emoji-picker-element/i18n/fr';\nimport de from 'emoji-picker-element/i18n/de';\n\n// French\npicker.i18n = fr;\n\n// German\npicker.i18n = de;\n```\n\nNote that translations for the interface (`i18n`) are not the same as translations for the emoji data (`dataSource` and `locale`). To support both, you should do something like:\n\n```js\nimport fr from 'emoji-picker-element/i18n/fr';\n\nconst picker = new Picker({ \n i18n: fr,\n locale: 'fr',\n dataSource: 'https://cdn.jsdelivr.net/npm/emoji-picker-element-data@^1/fr/emojibase/data.json',\n});\n```\n\nIf a built-in translation for your target language is not available, you can also write your own translation and pass it in as `i18n`. Please feel free to contribute your translation [here](https://github.com/nolanlawson/emoji-picker-element/tree/master/src/picker/i18n).\n\n#### Custom category order\n\nBy default, custom categories are sorted alphabetically. To change this, pass in your own `customCategorySorting`:\n\n```js\npicker.customCategorySorting = (category1, category2) =\u003e { /* your sorting code */ };\n```\n\nThis function should accept two strings and return a number.\n\nCustom emoji with no category will pass in `undefined`. By default, these are shown first, with the label `\"Custom\"`\n(determined by `i18n.categories.custom`).\n\n### Database\n\nYou can work with the database API separately, which allows you to query emoji the same\nway that the picker does:\n\n```js\nimport { Database } from 'emoji-picker-element';\n\nconst database = new Database();\nawait database.getEmojiBySearchPrefix('elephant'); // [{unicode: \"šŸ˜\", ...}]\n```\n\nNote that under the hood, IndexedDB data is partitioned based on the `locale`. So if you create two `Database`s with two different `locale`s, it will store twice as much data.\n\nAlso note that, unlike the picker, the database does not filter emoji based on whether they are supported by the current browser/OS or not. To detect emoji support, you can use a library like [is-emoji-supported](https://github.com/koala-interactive/is-emoji-supported).\n\nFull API:\n\n#### Constructors\n\n##### constructor\n\n\\+ **new Database**(`__namedParameters`: object): *Database*\n\nCreate a new Database.\n\nNote that multiple Databases pointing to the same locale will share the\nsame underlying IndexedDB connection and database.\n\n**Parameters:**\n\nā–Ŗ`Default value` **__namedParameters**: *object*= {}\n\nName | Type | Default | Description |\n------ | ------ | ------ | ------ |\n`customEmoji` | CustomEmoji[] | [] | Array of custom emoji |\n`dataSource` | string | \"https://cdn.jsdelivr.net/npm/emoji-picker-element-data@^1/en/emojibase/data.json\" | URL to fetch the emoji data from |\n`locale` | string | \"en\" | Locale string |\n\n**Returns:** *Database*\n\n#### Accessors\n\n##### customEmoji\n\nā€¢ **get customEmoji**(): *CustomEmoji[]*\n\nReturn the custom emoji associated with this Database, or the empty array if none.\n\n**Returns:** *CustomEmoji[]*\n\nā€¢ **set customEmoji**(`customEmoji`: CustomEmoji[]): *void*\n\nSet the custom emoji for this database. Throws an error if custom emoji are not in the correct format.\n\n**Parameters:**\n\nName | Type | Description |\n------ | ------ | ------ |\n`customEmoji` | CustomEmoji[] | |\n\n**Returns:** *void*\n\n#### Methods\n\n##### close\n\nā–ø **close**(): *Promiseā€¹voidā€ŗ*\n\nCloses the underlying IndexedDB connection. The Database is not usable after that (or any other Databases\nwith the same locale).\n\nNote that as soon as any other non-close/delete method is called, the database will automatically reopen.\n\n**Returns:** *Promiseā€¹voidā€ŗ*\n\n___\n\n##### delete\n\nā–ø **delete**(): *Promiseā€¹voidā€ŗ*\n\nDeletes the underlying IndexedDB database. The Database is not usable after that (or any other Databases\nwith the same locale).\n\nNote that as soon as any other non-close/delete method is called, the database will be recreated.\n\n**Returns:** *Promiseā€¹voidā€ŗ*\n\n___\n\n##### getEmojiByGroup\n\nā–ø **getEmojiByGroup**(`group`: number): *Promiseā€¹NativeEmoji[]ā€ŗ*\n\nReturns all emoji belonging to a group, ordered by `order`. Only returns native emoji;\ncustom emoji don't belong to a group.\n\nNon-numbers throw an error.\n\n**Parameters:**\n\nName | Type | Description |\n------ | ------ | ------ |\n`group` | number | the group number |\n\n**Returns:** *Promiseā€¹NativeEmoji[]ā€ŗ*\n\n___\n\n##### getEmojiBySearchQuery\n\nā–ø **getEmojiBySearchQuery**(`query`: string): *Promiseā€¹Emoji[]ā€ŗ*\n\nReturns all emoji matching the given search query, ordered by `order`.\n\nEmpty/null strings throw an error.\n\n**Parameters:**\n\nName | Type | Description |\n------ | ------ | ------ |\n`query` | string | search query string |\n\n**Returns:** *Promiseā€¹Emoji[]ā€ŗ*\n\n___\n\n##### getEmojiByShortcode\n\nā–ø **getEmojiByShortcode**(`shortcode`: string): *Promiseā€¹Emoji | nullā€ŗ*\n\nReturn a single emoji matching the shortcode, or null if not found.\n\nThe colons around the shortcode should not be included when querying, e.g.\nuse \"slight_smile\", not \":slight_smile:\". Uppercase versus lowercase\ndoes not matter. Empty/null strings throw an error.\n\n**Parameters:**\n\nName | Type | Description |\n------ | ------ | ------ |\n`shortcode` | string | |\n\n**Returns:** *Promiseā€¹Emoji | nullā€ŗ*\n\n___\n\n##### getEmojiByUnicodeOrName\n\nā–ø **getEmojiByUnicodeOrName**(`unicodeOrName`: string): *Promiseā€¹Emoji | nullā€ŗ*\n\nReturn a single native emoji matching the unicode string, or\na custom emoji matching the name, or null if not found.\n\nIn the case of native emoji, the unicode string can be either the\nmain unicode string, or the unicode of one of the skin tone variants.\n\nEmpty/null strings throw an error.\n\n**Parameters:**\n\nName | Type | Description |\n------ | ------ | ------ |\n`unicodeOrName` | string | unicode (native emoji) or name (custom emoji) |\n\n**Returns:** *Promiseā€¹Emoji | nullā€ŗ*\n\n___\n\n##### getPreferredSkinTone\n\nā–ø **getPreferredSkinTone**(): *Promiseā€¹SkinToneā€ŗ*\n\nGet the user's preferred skin tone. Returns 0 if not found.\n\n**Returns:** *Promiseā€¹SkinToneā€ŗ*\n\n___\n\n##### getTopFavoriteEmoji\n\nā–ø **getTopFavoriteEmoji**(`limit`: number): *Promiseā€¹Emoji[]ā€ŗ*\n\nGet the top favorite emoji in descending order. If there are no favorite emoji yet, returns an empty array.\n\n**Parameters:**\n\nName | Type | Description |\n------ | ------ | ------ |\n`limit` | number | maximum number of results to return |\n\n**Returns:** *Promiseā€¹Emoji[]ā€ŗ*\n\n___\n\n##### incrementFavoriteEmojiCount\n\nā–ø **incrementFavoriteEmojiCount**(`unicodeOrName`: string): *Promiseā€¹voidā€ŗ*\n\nIncrement the favorite count for an emoji by one. The unicode string must be non-empty. It should\ncorrespond to the base (non-skin-tone) unicode string from the emoji object, or in the case of\ncustom emoji, it should be the name.\n\n**Parameters:**\n\nName | Type | Description |\n------ | ------ | ------ |\n`unicodeOrName` | string | unicode of a native emoji, or name of a custom emoji |\n\n**Returns:** *Promiseā€¹voidā€ŗ*\n\n___\n\n##### ready\n\nā–ø **ready**(): *Promiseā€¹voidā€ŗ*\n\nResolves when the Database is ready, or throws an error if\nthe Database could not initialize.\n\nNote that you don't need to do this before calling other APIs ā€“ they will\nall wait for this promise to resolve before doing anything.\n\n**Returns:** *Promiseā€¹voidā€ŗ*\n\n___\n\n##### setPreferredSkinTone\n\nā–ø **setPreferredSkinTone**(`skinTone`: SkinTone): *Promiseā€¹voidā€ŗ*\n\nSet the user's preferred skin tone. Non-numbers throw an error.\n\n**Parameters:**\n\nName | Type | Description |\n------ | ------ | ------ |\n`skinTone` | SkinTone | preferred skin tone |\n\n**Returns:** *Promiseā€¹voidā€ŗ*\n\n### Custom emoji\n\nBoth the Picker and the Database support custom emoji. Unlike regular emoji, custom emoji\nare kept in-memory. (It's assumed that they're small, and they might frequently change, so\nthere's not much point in storing them in IndexedDB.)\n\nCustom emoji should follow the format:\n\n```js\n[\n {\n name: 'Garfield',\n shortcodes: ['garfield'],\n url: 'http://example.com/garfield.png',\n category: 'Cats'\n },\n {\n name: 'Heathcliff',\n shortcodes: ['heathcliff'],\n url: 'http://example.com/heathcliff.png',\n category: 'Cats'\n },\n {\n name: 'Scooby-Doo',\n shortcodes: ['scooby'],\n url: 'http://example.com/scooby.png',\n category: 'Dogs'\n } \n]\n```\n\nNote that names are assumed to be unique (case-insensitive), and it's assumed that the `shortcodes` have at least one entry.\n\nThe `category` is optional. If you don't provide it, then the custom emoji will appear in a\nsingle category called \"Custom\".\n\nTo pass custom emoji into the `Picker`:\n\n```js\nconst picker = new Picker({\n customEmoji: [ /* ... */ ]\n});\n```\n\nOr the `Database`:\n\n```js\nconst database = new Database({\n customEmoji: [ /* ... */ ]\n});\n```\n\nCustom emoji can also be set at runtime:\n\n```js\npicker.customEmoji = [ /* ... */ ];\ndatabase.customEmoji = [ /* ... */ ];\n```\n\n### Tree-shaking\n\nIf you want to import the `Database` without the `Picker`, or you want to code-split them separately, then do:\n\n```js\nimport Picker from 'emoji-picker-element/picker';\nimport Database from 'emoji-picker-element/database';\n```\n\nThe reason for this is that `Picker` automatically registers itself as a custom element, following [web component best practices](https://justinfagnani.com/2019/11/01/how-to-publish-web-components-to-npm/). But this adds side effects, so bundlers like Webpack and Rollup do not tree-shake as well, unless the modules are imported from completely separate files.\n\n### Within a meta-framework (Next.js, SvelteKit, etc.)\n\nSome meta-frameworks will attempt to server-side render (SSR) any dependencies you `import`. However, `emoji-picker-element` only supports client-side rendering ā€“ it does not work on the server side. If you attempt to import it on the server side, you will see an error like `requestAnimationFrame is not defined`.\n\nTo load `emoji-picker-element` only on the client side, use your meta-framework's technique for client-side-only imports. For example, you can use [dynamic `import()`s](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) with [`next/dynamic` in Next.js](https://stackoverflow.com/a/61881528/680742) or [`onMount()` in SvelteKit](https://www.banjocode.com/post/svelte/client-side-library).\n\n`emoji-picker-element` is not designed for SSR. In most apps, an emoji picker should be lazy-loaded upon user interaction (for example, when the user clicks a button).\n\n### Within a Svelte project\n\n\u003e [!WARNING] \n\u003e `emoji-picker-element` is no longer based on Svelte, so importing from `emoji-picker-element/svelte` is now deprecated.\n\nPreviously, `emoji-picker-element` was based on Svelte v3/v4, and you could do:\n\n```js\nimport Picker from 'emoji-picker-element/svelte';\n```\n\nThe goal was to slightly reduce the bundle size by sharing common `svelte` imports.\n\nThis is still supported for backwards compatibility, but it is deprecated and just re-exports the Picker. Instead, do:\n\n```js\nimport Picker from 'emoji-picker-element/picker';\n```\n\n## Data and offline\n\n### Data source and JSON format\n\nIf you'd like to host the emoji data (`dataSource`) yourself, you can do:\n\n npm install emoji-picker-element-data@^1\n\nThen host `node_modules/emoji-picker-element-data/en/emojibase/data.json` (or other JSON files) on your web server.\n\n```js\nconst picker = new Picker({\n dataSource: '/path/to/my/webserver/data.json'\n});\n```\n\nSee [`emoji-picker-element-data`](https://www.npmjs.com/package/emoji-picker-element-data) for details.\n\n### Shortcodes\n\nThere is no standard for shortcodes, so unlike other emoji data, there is some disagreement as to what a \"shortcode\" actually is.\n\n`emoji-picker-element-data` is based on `emojibase-data`, which offers several shortcode packs per language. For instance,\nyou may choose shortcodes from GitHub, Slack, Discord, or Emojibase (the default). You\ncan browse the available data files [on jsdelivr](https://www.jsdelivr.com/package/npm/emoji-picker-element-data) and see\nmore details on shortcodes [in the Emojibase docs](https://emojibase.dev/docs/shortcodes).\n\n### Cache performance\n\nFor optimal cache performance, it's recommended that your server expose an `ETag` header. If so, `emoji-picker-element` can avoid re-downloading the entire JSON file over and over again. Instead, it will do a `HEAD` request and just check the `ETag`.\n\nIf the server hosting the JSON file is not the same as the one containing the emoji picker, then the cross-origin server will also need to expose `Access-Control-Allow-Origin: *` and `Access-Control-Expose-Headers: ETag` (or `Access-Control-Expose-Headers: *` ). `jsdelivr` already does this, which is partly why it is the default.\n\nIf `emoji-picker-element` cannot use the `ETag` for any reason, it will fall back to the less performant option, doing a full `GET` request on every page load.\n\n### emojibase-data compatibility (deprecated)\n\n_**Deprecated:** in v1.3.0, `emoji-picker-element` switched from [`emojibase-data`](https://github.com/milesj/emojibase) to\n[`emoji-picker-element-data`](https://npmjs.com/package/emoji-picker-element-data) as its default data source. You can still use `emojibase-data`, but only v5 is supported, not v6. Support may be removed in a later release._\n\nWhen using `emojibase-data`, you must use the _full_ [`emojibase-data`](https://github.com/milesj/emojibase) JSON file, not the \"compact\" one (i.e. `data.json`, not `compact.json`).\n\n### Trimming the emoji data (deprecated)\n\n_**Deprecated:** in v1.3.0, `emoji-picker-element` switched from [`emojibase-data`](https://github.com/milesj/emojibase) to\n[`emoji-picker-element-data`](https://npmjs.com/package/emoji-picker-element-data) as its default data source. With the new `emoji-picker-element-data`, there is no need to trim the emoji down to size. This function is deprecated and may be removed eventually._\n\nIf you are hosting the `emojibase-data` JSON file yourself and would like it to be as small as possible, then you can use the utility `trimEmojiData` function:\n\n```js\nimport trimEmojiData from 'emoji-picker-element/trimEmojiData.js';\nimport emojiBaseData from 'emojibase-data/en/data.json';\n\nconst trimmedData = trimEmojiData(emojiBaseData);\n```\n\nOr if your version of Node doesn't support ES modules:\n\n```js\nconst trimEmojiData = require('emoji-picker-element/trimEmojiData.cjs');\n```\n\n### Offline-first\n\n`emoji-picker-element` uses a \"stale while revalidate\" strategy to update emoji data. In other words, it will use any existing data it finds in IndexedDB, and lazily update via the `dataSource` in case that data has changed. This means it will work [offline-first](http://offlinefirst.org/) the second time it runs.\n\nIf you would like to manage the database yourself (e.g. to ensure that it's correctly populated before displaying the `Picker`), then create a new `Database` instance and wait for its `ready()` promise to resolve:\n\n```js\nconst database = new Database();\ntry {\n await database.ready();\n} catch (err) {\n // Deal with any errors (e.g. offline)\n}\n```\n\nIf `emoji-picker-element` fails to fetch the JSON data the first time it loads, then it will display an error message.\n\n### Environments without IndexedDB\n\n`emoji-picker-element` has a hard requirement on [IndexedDB](https://developer.mozilla.org/en-US/docs/Glossary/IndexedDB), and will not work without it.\n\nFor browsers that don't support IndexedDB, such as [Firefox in private browsing mode](https://bugzilla.mozilla.org/show_bug.cgi?id=1639542), you can polyfill it using [fake-indexeddb](https://github.com/dumbmatter/fakeIndexedDB). Here is [a working example](https://bl.ocks.org/nolanlawson/651e6fbe4356ff098f505e6cc5fb8cd8) and [more details](https://github.com/nolanlawson/emoji-picker-element/issues/9).\n\nFor Node.js environments such as [Jest](https://jestjs.io/) or [JSDom](https://github.com/jsdom/jsdom), you can also use fake-indexeddb. A [working example](https://github.com/nolanlawson/emoji-picker-element/blob/39c50c3ce4c4c4d2cd8a15f337a722ad86c739e9/config/jest.setup.js#L28-L29) can be found in the tests for this very project.\n\n## Design decisions\n\nSome of the reasoning behind why `emoji-picker-element` is built the way it is.\n\n### IndexedDB\n\nThe [`emojibase-data`](https://github.com/milesj/emojibase) English JSON file is [854kB](https://unpkg.com/browse/emojibase-data@5.0.1/en/), and the \"compact\" version is still 543kB. That's a lot of data to keep in memory just for an emoji picker. And it's not as if that number is ever going down; the Unicode Consortium keeps adding more emoji every year.\n\nUsing IndexedDB has a few advantages:\n\n1. We don't need to keep the full emoji data in memory at all times.\n2. After the first load, there is no need to download, parse, and index the JSON file again, because it's already available in IndexedDB.\n3. If you want, you can even [load the IndexedDB data in a web worker](https://github.com/nolanlawson/emoji-picker-element/blob/ff86a42/test/adhoc/worker.js), keeping the main thread free from non-UI data processing.\n\n### Native emoji\n\nTo avoid downloading a large sprite sheet or font file ā€“ which may look out-of-place on different platforms, or may have [IP issues](https://blog.emojipedia.org/apples-emoji-crackdown/) ā€“ `emoji-picker-element` only renders native emoji by default. This means it is limited to the emoji font actually installed on the user's device.\n\nTo avoid rendering ugly unsupported or half-supported emoji, `emoji-picker-element` will automatically detect emoji support and only render the supported characters. (So no empty boxes or awkward double emoji.) If no color emoji are supported by the browser/OS, then an error message is displayed (e.g. older browsers, some odd Linux configurations).\n\nThat said, `emoji-picker-element` does support [custom emoji fonts](#custom-emoji-font) if you really want.\n\n### JSON loading\n\nBrowsers deal with JSON more efficiently when it's loaded via `fetch()` rather than embedded in JavaScript. It's\n[faster for the browser to parse JSON than JavaScript](https://joreteg.com/blog/improving-redux-state-transfer-performance),\nbecuase the data is being parsed in the more tightly-constrained JSON format than the generic JavaScript format.\n\nPlus, embedding the JSON directly would mean re-parsing the entire object on second load, which is something we want to avoid since the data is already in IndexedDB.\n\n### Browser support\n\n`emoji-picker-element` only supports the latest versions of Chrome, Firefox, and Safari, as well as equivalent browsers (Edge, Opera, etc.). If you need support for older browsers, you will need polyfills for the following things (non-exhaustive list):\n\n- Custom elements\n- Shadow DOM\n- ES2019+\n\nThat said, older browsers may not have a color emoji font installed at all, so `emoji-picker-element` will not work in those cases.\n\n## Contributing\n\nSee [CONTRIBUTING.md](https://github.com/nolanlawson/emoji-picker-element/blob/master/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnolanlawson%2Femoji-picker-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnolanlawson%2Femoji-picker-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnolanlawson%2Femoji-picker-element/lists"}