Emoji Picker
<quiet-emoji-picker>
Lets users find and pick an emoji from a searchable grid, with names and keywords in their own language. Reach for it wherever a message, comment, or reaction needs an emoji and picking one should take a click and a keystroke rather than a hunt.
Emoji names and search keywords come from Unicode . Emoji the device can't render are left out, and recently used emoji and the preferred skin tone are remembered between visits.
<div id="emoji-picker__overview">
<quiet-text-area
id="emoji-picker__overview-message"
label="Message"
value="Meowy McGee just knocked a glass off the counter and walked away like nothing happened "
rows="3"
></quiet-text-area>
<quiet-emoji-picker for="emoji-picker__overview-message">
<quiet-button slot="trigger" icon-label="Add emoji">
<quiet-icon name="mood-smile"></quiet-icon>
</quiet-button>
</quiet-emoji-picker>
</div>
<style>
#emoji-picker__overview {
display: flex;
flex-direction: column;
align-items: start;
gap: 0.5rem;
max-width: 400px;
}
</style>
Emoji data loads from the library's assets/emoji/ folder as soon as the picker connects. If
you're self-hosting, make sure the library path is set.
Examples Jump to heading
Adding a trigger Jump to heading
Slot a button into the trigger slot and the picker will
open in a popup anchored to it. The search field will receive focus when the popup opens, except on touch
devices, where the on-screen keyboard would cover the picker. Picking an emoji will close the popup. The
trigger must be a <quiet-button> or a native <button>.
<quiet-emoji-picker id="emoji-picker__trigger">
<quiet-button slot="trigger">
<quiet-icon slot="start" name="mood-smile"></quiet-icon>
Pick an emoji
</quiet-button>
</quiet-emoji-picker>
<quiet-emoji-picker id="emoji-picker__trigger-native">
<button slot="trigger">Native button</button>
</quiet-emoji-picker>
Inserting into a field Jump to heading
Set the for attribute to the ID of a field and the picker will insert the emoji at the caret,
dispatch input and change events, and return focus to the field. This works with
native inputs and text areas, Quiet's text field and
text area, the
rich text editor, and any
contenteditable element. With the rich text editor, you can slot the picker into its
actions slot to put the trigger right in the toolbar.
<quiet-rich-text-editor
id="emoji-picker__insert-editor"
label="Adoption notes"
toolbar="bold italic underline | link | actions"
value="<p>Mittens is a gentle three-year-old tabby who loves sunbeams and will trade anything for a treat</p>"
style="max-width: 480px;"
>
<quiet-emoji-picker slot="actions" for="emoji-picker__insert-editor">
<quiet-button slot="trigger" appearance="text" icon-label="Add emoji">
<quiet-icon name="mood-smile"></quiet-icon>
</quiet-button>
</quiet-emoji-picker>
</quiet-rich-text-editor>
Listening for selections Jump to heading
When the user picks an emoji, the quiet-emoji-select event will be emitted. You can inspect
event.detail.emoji to get the emoji and event.detail.label to get its name. It
will be emitted on every pick, even of the same emoji, so it works well for reactions. To keep the picker
open and handle the insertion yourself, call event.preventDefault().
Chairman Meow has approved this nap.
<div id="emoji-picker__reactions">
<quiet-card style="max-width: 340px;">
<img
slot="media"
src="https://images.unsplash.com/photo-1574158622682-e40e69881006?q=80&w=600&auto=format&fit=crop"
alt="A gray tabby cat lies on its back with its paws in the air."
>
<p>Chairman Meow has approved this nap.</p>
<div class="reactions">
<quiet-emoji-picker placement="top-start">
<quiet-button slot="trigger" size="sm" pill icon-label="Add reaction">
<quiet-icon name="mood-plus"></quiet-icon>
</quiet-button>
</quiet-emoji-picker>
</div>
</quiet-card>
</div>
<script>
const container = document.getElementById('emoji-picker__reactions');
const picker = container.querySelector('quiet-emoji-picker');
const reactions = container.querySelector('.reactions');
picker.addEventListener('quiet-emoji-select', event => {
const { emoji, label } = event.detail;
let reaction = reactions.querySelector(`[data-emoji="${emoji}"]`);
// Bump the count when the reaction already exists, otherwise add it
if (reaction) {
const count = reaction.querySelector('span');
count.textContent = Number(count.textContent) + 1;
} else {
reaction = document.createElement('quiet-button');
reaction.size = 'sm';
reaction.pill = true;
reaction.dataset.emoji = emoji;
reaction.title = label;
reaction.innerHTML = `${emoji} <span>1</span>`;
reactions.insertBefore(reaction, picker);
}
});
</script>
<style>
#emoji-picker__reactions {
.reactions {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 0.5rem;
}
quiet-button span {
color: var(--quiet-text-muted);
}
}
</style>
Searching Jump to heading
You can search by an emoji's name or any of its keywords, so "happy", "grin", and
"teeth" will all find the grinning face. Shortcodes such as :tada:,
:+1:, and :heart_eyes: will work with or without the colons, and emoticons such as
:D and <3 will match exactly. The best match will be highlighted as you type,
so pressing Enter will pick it. Try "tada", ":D", or "cat heart" in
the picker below.
<quiet-emoji-picker id="emoji-picker__search">
<quiet-button slot="trigger">
<quiet-icon slot="start" name="mood-smile"></quiet-icon>
Pick an emoji
</quiet-button>
</quiet-emoji-picker>
Rendering inline Jump to heading
Omit the trigger and the picker will render in place. This is useful when the picker is the main thing on
the page, or when it lives inside something you control, such as a
dialog. You can use the label attribute to give it a more
specific accessible name. It won't be visible, but it will be announced by assistive devices.
<quiet-emoji-picker id="emoji-picker__inline" label="Pick a mood"></quiet-emoji-picker>
Skin tones Jump to heading
Users can choose a skin tone with the button at the end of the footer. The choice will apply to every emoji
that supports one and will be shared by every picker that uses the same
storage key. Add the without-skin-tones attribute to
hide the selector and show every emoji in its default tone.
<quiet-emoji-picker without-skin-tones>
<quiet-button slot="trigger">No skin tones</quiet-button>
</quiet-emoji-picker>
You can set a default with the tone attribute, where 0 is the default tone and
1 through 5 are light, medium-light, medium, medium-dark, and dark. A tone the
user has already chosen will take precedence, so the attribute only applies until they pick one. Setting the
tone property after the picker has rendered will apply it and remember it. If your users'
preferences live on your server, turn storage off and set
tone yourself.
Remembering preferences Jump to heading
Recently used emoji and the preferred skin tone will be saved to localStorage under the key
quiet-emoji-picker, and every picker that shares a key will stay in sync. Use the
storage-key attribute to keep separate preferences for different parts of your app, or set it
to an empty string to turn persistence off. A picker that doesn't persist will start fresh on every page
load, with the tone from the tone attribute if one is set.
<quiet-emoji-picker storage-key="" tone="3">
<quiet-button slot="trigger">Starts fresh, medium tone</quiet-button>
</quiet-emoji-picker>
Recently used Jump to heading
Emoji the user picks will collect in a "Recently used" group at the top of the picker, most recent
first. Keyboard users can remove one by focusing it and pressing Backspace or Delete.
Add the without-recents attribute to hide the group.
<quiet-emoji-picker without-recents>
<quiet-button slot="trigger">No recents</quiet-button>
</quiet-emoji-picker>
Changing the placement Jump to heading
You can set the preferred placement of the popup with the placement attribute. The popup will
shift to a more optimal location if the preferred placement doesn't have enough room. The default placement
is bottom-start.
<quiet-emoji-picker placement="top-start">
<quiet-button slot="trigger">Top start</quiet-button>
</quiet-emoji-picker>
<quiet-emoji-picker placement="bottom-end">
<quiet-button slot="trigger">Bottom end</quiet-button>
</quiet-emoji-picker>
<quiet-emoji-picker placement="right-start">
<quiet-button slot="trigger">Right start</quiet-button>
</quiet-emoji-picker>
Localization Jump to heading
Emoji names, search keywords, and skin tone names are localized using the component's
lang attribute, and the picker loads that language's emoji data on its own. Import the
corresponding translation so the UI strings, such as the search placeholder and group names, are available
too. For right-to-left languages, also set dir="rtl". Emoji that haven't been
translated into a language yet keep their English names and keywords, and shortcodes such as
:tada: will work in every language. Try searching for "chat" in the French picker or
"ใญใ" in the Japanese one.
<quiet-emoji-picker lang="fr">
<quiet-button slot="trigger">Franรงais</quiet-button>
</quiet-emoji-picker>
<quiet-emoji-picker lang="ja">
<quiet-button slot="trigger">ๆฅๆฌ่ช</quiet-button>
</quiet-emoji-picker>
<quiet-emoji-picker lang="ar" dir="rtl">
<quiet-button slot="trigger">ุงูุนุฑุจูุฉ</quiet-button>
</quiet-emoji-picker>
<script type="module">
import '/dist/translations/fr.js';
import '/dist/translations/ja.js';
import '/dist/translations/ar.js';
</script>
This component also updates based on the page's language, which can be set using
<html lang="...">.
Using the emoji data Jump to heading
You can use the picker's emoji names, shortcodes, and rendering check in your own code, such as to label
reaction buttons or to store messages as shortcodes. Await the getEmojiData() method on any
picker. The data will be in the picker's current language.
<quiet-emoji-picker id="emoji-picker__data">
<quiet-button slot="trigger">Pick an emoji</quiet-button>
</quiet-emoji-picker>
<script type="module">
import { allDefined } from '/dist/quiet.js';
await allDefined();
const picker = document.getElementById('emoji-picker__data');
const emoji = await picker.getEmojiData();
emoji.label('๐๐ฟ'); // 'waving hand: dark skin tone'
emoji.toShortcode('๐'); // ':tada:'
emoji.fromShortcode(':tada:'); // '๐'
emoji.canRender('๐ซจ'); // false if the device can't draw it
emoji.search('cat heart', { limit: 8 }); // matching emoji, best match first
emoji.find(':wave:'); // the full record, with skin tone variants and every shortcode
</script>
Shortcodes are English in every language and don't include skin tones. Emoji added in recent Unicode
releases may not have shortcodes yet, so toShortcode() will return undefined for
them.
Pair search() with the
text area or
rich text editor's suggestions property to
offer emoji as the user types a : shortcode, the same way chat apps do.
<div id="emoji-picker__typeahead">
<quiet-text-area label="Message" placeholder="Type : followed by an emoji name, such as :cat" rows="3"></quiet-text-area>
<quiet-emoji-picker>
<quiet-button slot="trigger" icon-label="Add emoji">
<quiet-icon name="mood-smile"></quiet-icon>
</quiet-button>
</quiet-emoji-picker>
</div>
<script type="module">
import { allDefined } from '/dist/quiet.js';
await allDefined();
const container = document.getElementById('emoji-picker__typeahead');
const textArea = container.querySelector('quiet-text-area');
const picker = container.querySelector('quiet-emoji-picker');
const emoji = await picker.getEmojiData();
textArea.suggestions = [
{
trigger: ':',
getItems: query =>
emoji.search(query, { limit: 8 }).map(match => ({
label: `${match.emoji} ${match.label}`,
value: match.emoji
}))
}
];
</script>
<style>
#emoji-picker__typeahead {
display: flex;
flex-direction: column;
align-items: start;
gap: 0.5rem;
max-width: 400px;
}
</style>
Styling emoji pickers Jump to heading
Emoji pickers come with a simple, minimal appearance. Feel free to customize them with your own styles. Use
the --width and --height custom properties to size the panel, and apply
font-size to scale everything inside it. The search field, group buttons, group labels, emoji,
and footer are all exposed as CSS parts. Here's a tinted version built on the
primary palette, for inspiration.
<quiet-emoji-picker id="emoji-picker__styled" label="Pick an emoji"></quiet-emoji-picker>
<style>
#emoji-picker__styled {
--width: 20em;
--height: 22em;
font-size: 0.875rem;
&::part(panel) {
border-color: var(--quiet-primary-stroke-soft);
border-radius: var(--quiet-border-radius-xl);
background-color: var(--quiet-primary-fill-softer);
box-shadow: var(--quiet-shadow-soft);
}
&::part(search-box) {
border-color: var(--quiet-primary-stroke-soft);
border-radius: var(--quiet-border-radius-pill);
}
/* Tone separates the regions here, so the dividing lines go away */
&::part(groups) {
border-block-end-color: transparent;
}
/* Square buttons become circles, and the idle icons pick up the tint */
&::part(group-button) {
aspect-ratio: 1;
height: auto;
border-radius: var(--quiet-border-radius-circle);
color: var(--quiet-primary-text-on-soft);
}
&::part(group-button):hover {
background-color: var(--quiet-primary-fill-soft);
}
&::part(group-button-current),
&::part(group-button-current):hover {
background-color: var(--quiet-primary-fill-mid);
color: var(--quiet-primary-text-on-mid);
}
/* The filled pill replaces the underline */
&::part(group-button-current)::after {
display: none;
}
/* Group labels are sticky, so they need the panel's background to scroll cleanly */
&::part(group-label) {
background-color: var(--quiet-primary-fill-softer);
color: var(--quiet-primary-text-colorful);
font-size: 0.75em;
letter-spacing: 0.05em;
text-transform: uppercase;
}
&::part(option) {
border-radius: var(--quiet-border-radius-circle);
}
&::part(option):hover {
background-color: var(--quiet-primary-fill-soft);
}
&::part(footer) {
border-block-start-color: transparent;
background-color: var(--quiet-primary-fill-soft);
}
&::part(preview-label) {
font-weight: var(--quiet-font-weight-semibold);
}
&::part(skin-tone-button),
&::part(skin-tones) {
border-radius: var(--quiet-border-radius-pill);
}
&::part(skin-tone-button):hover {
background-color: var(--quiet-primary-fill-soft);
}
}
</style>
Keyboard support Jump to heading
Tab to the trigger and press Enter or Space to open the picker, or Tab to an inline picker's search field, then use the keys below.
| Key | Action |
|---|---|
| Type a character or Backspace | Edits the search, moving focus back to the search field from the grid |
| โ | Moves down a level, from the search field to the group buttons and from a group button into its group, or straight into the grid while searching |
| โ | Moves back up a level, from the grid's first row to the group buttons and from a group button to the search field |
| โ โ โ โ | Moves through the grid, or between group buttons with โ โ, jumping to each group (reversed in RTL) |
| Home End | Jumps to the first or last emoji, or to the first or last group from the group buttons |
| Page Up Page Down | Jumps to the previous or next group, or four rows at a time while searching |
| Enter Space | Picks the highlighted emoji and closes the popup (Space works in the grid only) |
| Picks the highlighted emoji and keeps the picker open | |
| Backspace Delete | Removes the focused emoji from the recently used group |
| Escape | Clears the search, then closes the popup and returns focus to the trigger |
Tab to the skin tone button and press Enter or Space to open the menu, then use the keys below.
| Key | Action |
|---|---|
| โ โ โ โ | Moves between skin tones, wrapping at either end |
| Home End | Jumps to the first or last skin tone |
| Enter Space | Picks the skin tone and closes the menu |
| Escape | Closes the menu without changing the skin tone |
API Jump to heading
Importing Jump to heading
The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.
To manually import <quiet-emoji-picker> from the CDN, use the following code.
import 'https://cdn.quietui.org/v6.7.0/components/emoji-picker/emoji-picker.js';
To manually import <quiet-emoji-picker> from a self-hosted distribution, use the
following code. Remember to replace /path/to/quiet with the appropriate local path.
import '/path/to/quiet/components/emoji-picker/emoji-picker.js';
Slots Jump to heading
Emoji Picker supports the following slots. Learn more about using slots
| Name | Description |
|---|---|
trigger
|
An optional button that opens the picker in a popup anchored to it. Must be a
<quiet-button> or <button> element. Without a trigger, the
picker renders inline.
|
Properties Jump to heading
Emoji Picker has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties
| Property | Description | Reflects | Type | Default |
|---|---|---|---|---|
label
|
An accessible label for the picker. This won't be visible, but it will be announced by assistive devices. Defaults to a localized "Emoji picker". |
|
string
|
|
value
|
The most recently picked emoji. |
|
string
|
''
|
for
|
The ID of an element to insert emoji into: a native input or textarea, a Quiet text field or text
area, a rich text editor, or any contenteditable element. The emoji is inserted at the
caret, input and change events are dispatched, and focus returns to the element.
|
|
string
|
|
open
|
Shows or hides the popup. Only applies when a trigger is slotted in. |
|
boolean
|
false
|
placement
|
The placement of the popup in reference to the trigger. The popup will shift to a more optimal location if the preferred placement doesn't have enough room. |
|
QuietPlacement
|
'bottom-start'
|
distance
|
The distance of the popup from its trigger. |
|
number
|
4
|
offset
|
The offset of the popup along its trigger. |
|
number
|
0
|
withoutRecents
without-recents
|
Hides the group of recently used emoji. |
|
boolean
|
false
|
withoutSkinTones
without-skin-tones
|
Hides the skin tone selector and shows every emoji in its default tone. |
|
boolean
|
false
|
tone
|
The skin tone applied to emoji that support one, where 0 is the default tone and 1โ5 run from light to dark. Users can change it from the footer. When storage is enabled, a tone the user has already chosen takes precedence over this attribute, and changes made here or by the user are remembered. |
|
number
|
0
|
storageKey
storage-key
|
The localStorage key under which recently used emoji and the preferred skin tone are remembered. Pickers that share a key stay in sync with each other. Set this to an empty string to turn persistence off. |
|
string
|
'quiet-emoji-picker'
|
Methods Jump to heading
Emoji Picker supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods
| Name | Description | Arguments |
|---|---|---|
focus() |
Sets focus to the picker. With a trigger, focus goes to the trigger while the popup is closed. Otherwise, it goes to the search field. |
options: FocusOptions
|
blur() |
Removes focus from the picker. | |
getEmojiData() |
Resolves with the emoji data for the picker's language: localized names, shortcodes, and a rendering check you can use elsewhere on the page, e.g. to label reactions or convert shortcodes. The data is cached, so awaiting this more than once costs nothing, and calling it again after the language changes gets that language's data. It rejects only when no data file can be fetched at all. |
Events Jump to heading
Emoji Picker dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events
| Name | Description |
|---|---|
quiet-emoji-select |
Emitted when the user picks an emoji. event.detail.emoji is the emoji and
event.detail.label is its name in the picker's language. Calling
event.preventDefault() keeps the picker from inserting the emoji into the
for element and from closing.
|
quiet-before-open |
Emitted when the popup is instructed to open but before it is shown. Calling
event.preventDefault() will prevent it from opening.
|
quiet-open |
Emitted when the popup has opened and the animation has completed. |
quiet-before-close |
Emitted when the popup is dismissed but before it is hidden. Calling
event.preventDefault() will prevent it from closing.
|
quiet-close |
Emitted when the popup has closed and the animation has completed. |
CSS custom properties Jump to heading
Emoji Picker supports the following CSS custom properties. You can style them like any other CSS property. Learn more about CSS custom properties
| Name | Description | Default |
|---|---|---|
--width |
The width of the picker. |
22em
|
--height |
The height of the picker. |
24em
|
--show-duration |
The duration of the popup's show animation. |
50ms
|
--hide-duration |
The duration of the popup's hide animation. |
50ms
|
CSS parts Jump to heading
Emoji Picker exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts
| Name | Description | CSS selector |
|---|---|---|
panel |
The element that contains the picker, a <div>. |
::part(panel)
|
search-box |
The element that wraps the search field and its icon. |
::part(search-box)
|
search |
The search field, an <input> element. |
::part(search)
|
clear-button |
The button that clears the search, a <button> element. Only rendered while
searching.
|
::part(clear-button)
|
groups |
The row of buttons that jump to each group. |
::part(groups)
|
group-button |
A button that scrolls to a group. The group currently in view also has the
group-button-current part.
|
::part(group-button)
|
group-button-current |
The group button for the group currently in view. |
::part(group-button-current)
|
listbox |
The scrolling container that holds the emoji. |
::part(listbox)
|
group |
A group of emoji and its heading. |
::part(group)
|
group-label |
The heading above each group. |
::part(group-label)
|
grid |
The grid of emoji inside a group. |
::part(grid)
|
option |
An emoji button. |
::part(option)
|
no-results |
The empty state shown when a search matches nothing. |
::part(no-results)
|
footer |
The element that wraps the preview and skin tone controls. |
::part(footer)
|
preview |
The element that shows the active emoji and its name. |
::part(preview)
|
preview-emoji |
The active emoji in the preview. |
::part(preview-emoji)
|
preview-label |
The active emoji's name in the preview. |
::part(preview-label)
|
skin-tone-button |
The button that reveals the skin tone options. |
::part(skin-tone-button)
|
skin-tones |
The container that holds the skin tone options. Only rendered while open. |
::part(skin-tones)
|
skin-tone |
A skin tone option, a <button> element. |
::part(skin-tone)
|
Custom States Jump to heading
Emoji Picker has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states
| Name | Description | CSS selector |
|---|---|---|
has-trigger |
Applied when a trigger is slotted in and the picker renders as a popup. |
:state(has-trigger)
|
open |
Applied when the popup is open. |
:state(open)
|
Dependencies Jump to heading
Emoji Picker automatically imports the following elements. Sub-dependencies are also included in this list.