Skip to content

Emoji Picker

<quiet-emoji-picker> stable since 6.6

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 CLDR . 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>.

Pick an emoji
<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().

A gray tabby cat lies on its back with its paws in the air.

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.

Pick an emoji
<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.

No skin tones
<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.

Starts fresh, medium tone
<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.

No recents
<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.

Top start Bottom end Right 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.

Franรงais ๆ—ฅๆœฌ่ชž ุงู„ุนุฑุจูŠุฉ
<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)
+ Enter Space 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.

CDN Self-hosted

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.

Search this website Toggle dark mode View the code on GitHub Follow @quietui.org on Bluesky Follow @quiet_ui on X

    No results found