PicMo Documentation

PicMo is modular and consists of three main packages depending on your requirements:

• picmo: The core package used to create an inline picker.
• @picmo/popup-picker: Extends the core to allow creating a popup-style picker.
• @picmo/renderer-twemoji: Provides support for rendering emojis using Twemoji images instead of default OS images.

PicMo is a plain JavaScript emoji picker widget that can be integrated into your application in two primary ways:

1. Standalone Inline Picker: The emoji picker is rendered directly and immediately within the page layout.
2. Popup Picker: The picker is contained within a popup, which is triggered by user interaction with a button or other element.

PicMo uses Emojibase for its emoji data, which is cached locally in an IndexedDB database for performance.

The PicMo picker is composed of several independent functional elements that work together to provide an emoji selection experience:

• Search: Allows users to find specific emojis by text.
• Category tabs: Provides quick navigation to specific emoji categories.
• Recents: A dedicated section that tracks and displays recently used emojis.
• Emoji grid: The main browsing area where users select emojis.
• Preview: A visual area that displays a larger version of an emoji when it is hovered or focused.
• Variant popup: An interface that appears when an emoji has multiple variations (e.g., skin tones) to allow the user to select a specific one.

The EmojiRecord type describes a single emoji as it exists within the picker or a recents provider.

Important Distinction: EmojiRecord is an internal representation used for managing the emoji list and is not the object emitted when a user selects an emoji. To find out what is returned upon selection, refer to the EmojiSelection documentation.

To use a custom emoji source (like JoyPixels), you can create a subclass of the Renderer class from picmo. A custom renderer must implement two specific methods to handle how emojis are displayed in the picker and what data is returned when an emoji is selected.

import { Renderer } from 'picmo';

// A Renderer subclass must implement 'render' and 'emit'

Custom images are defined using the CustomEmoji interface. Each object in the custom array must follow these rules:

• emoji: A unique string that serves as the identifier for the image. This value must be unique across all custom images.
• label: A string describing the emoji.
• url: The source URL for the image.
• tags: An array of strings used for filtering. Note that all custom images are automatically assigned the custom tag, but you can add your own additional tags here.
• data: An optional object containing arbitrary data. This data is preserved and included in the emitted data when the custom emoji is selected.

When an emoji that supports multiple variants (such as different skin tones, hair colors, or genders) is selected in the picker, a variant popup is displayed. This popup includes the original emoji and all available variants.

Selecting a variant will close the popup and emit the specific variant emoji. Note that variants associated with newer Emoji versions that are not supported by the current version of Emoji will not be displayed.

In PopupOptions, you can define two key elements:

• triggerElement: The element that acts as the trigger for the popup. The popup detects clicks on this element to handle closing when clicking outside.
• referenceElement: The element that the popup is positioned relative to.

Note: The popup does not add event listeners to these elements. You must add your own listeners (like click) to the triggerElement to call picker.open() or picker.toggle().

Sharing a popup: You can override these elements dynamically by passing them as arguments to the .open(options) or .toggle(options) methods on the PopupPickerController.

PicMo is modular to help minimize bundle size. Depending on your requirements, you can choose which packages to install:

• picmo: The core package. This is required for all other packages to function. It provides the ability to create inline emoji pickers using native emoji rendering.
• @picmo/popup-picker: An add-on package that extends the core functionality to support popup-style emoji pickers.
• @picmo/renderer-twemoji: An add-on package that allows you to render emojis using the Twemoji library instead of native rendering.

The EmojiSelection object returned by the emoji:select event contains different properties based on the emoji type:

Native Emojis

Includes the character, hex code, and localized label:

{
  emoji: '😀',
  hexcode: '1F600',
  label: 'grinning face',
}

Twemoji Emojis

Includes all native emoji properties plus a url pointing to the Twemoji SVG image:

{
  emoji: '😀',
  hexcode: '1F600',
  label: 'grinning face',
  url: 'https://twemoji.maxcdn.com/v/14.0.1/svg/1f600.svg'
}

Custom Images

Includes the base emoji data, the image url, and any arbitrary data provided in the data property:

{
  emoji: 'kitty1',
  label: 'Cute kitty',
  url: 'https://placekitten.com/200/200',
  data: { id: 1 }
}