API Documentation

EmojiButton Class

The EmojiButton class creates and controls an emoji picker instance. It is a named export from the @joeattardi/emoji-button module. It can be imported as follows:

import { EmojiButton } from '@joeattardi/emoji-button';


The constructor for the EmojiButton class. Accepts an optional options parameter, which is an object specifying any desired options (shown below).

Supported options are:

autoHidebooleantrueWhether or not the picker should be automatically hidden when an emoji is selected.
autoFocusSearchbooleantrueWhether or not to automatically focus the search field when the picker is shown.
categoriesstring arrayall categoriesAn array of the categories to include in the picker. See Category IDs for a list of valid values.
customcustom emoji definition arraynoneAn array of the custom emojis to add to the Custom category. Each element of the array should have two properties:
  • name: The custom emoji's display name.
  • emoji: The URL (absolute or relative) of the custom emoji image.
emojiDataobjectBuilt-in emoji dataThe custom emoji data to use. This is typically used for providing translated emoji names, such as from the @roderickhsiao/emoji-button-locale-data package.
emojiSizestring'1.8em'The size to use for the emoji icons. This can be any valid CSS size expression.
emojisPerRownumber8The number of emojis to display per row. If this is set to a number smaller than 6, the picker will be so narrow that some of the category buttons will be cut off. In this case, it is advisable to set showCategoryButtons to false.
emojiVersionstring'12.1'The version of the Emoji specification to use. This determines which emojis are available in the picker. Valid values are:
  • '1.0'
  • '2.0'
  • '3.0'
  • '4.0'
  • '5.0'
  • '11.0'
  • '12.0'
  • '12.1'
i18nobjectSee I18N Strings.An object containing localized messages to display in the UI. See I18N Strings for the object format and default values.
iconsicon definition objectnoneThe custom icons, if any, to use. The object provided must be an icon definition object. Not all properties have to be provided - only the icons you want to override.
initialCategorystring'smileys'The ID of the category to show initially when the picker is shown. See Category IDs for a list of valid category IDs.
pluginsplugin definition arraynoneAn array of plugins to use with the picker. See Plugins for more details. A plugin is an object containing the following functions:
  • render(picker): Renders the UI for the plugin.
  • destroy (optional): Performs any necessary cleanup for the plugin when the picker is destroyed.
positionstring or object'auto'The position of the picker relative to the reference element. This can either be a string correpsonding to one of the Popper options, or an object with top, bottom, left, and/or right for fixed positioning. See the Popper documentation for a list of valid relative position values.
recentsCountnumber50The number of recent emojis to save.
rootElementHTML element referencedocument.bodyThe root DOM node to attach the picker element to.
rowsnumber6The number of visible rows in the picker.
showAnimationbooleantrueWhether or not to show animations in the picker.
showCategoryButtonsbooleantrueWhether or not to show the category buttons. If emojisPerRow is 6 or less, it is recommended to set this to false.
showPreviewbooleantrueWhether or not to show the preview area.
showSearchbooleantrueWhether or not to show the search field.
showRecentsbooleantrueWhether or not to show (and save) recently selected emojis.
showVariantsbooleantrueWhether or not to support emoji skin tone variants.
stylestring'native'The style to use for the emojis. Valid styles are:
  • 'native': Use the operating system's native emoji characters.
  • 'twemoji': Use the cross-platform Twemoji images.
themestring'light'The theme to use for the picker. Valid themes are:
  • 'light': Use the light theme.
  • 'dark': Use the dark theme.
  • 'auto': Use the operating system setting.
twemojiOptionsobject{ ext: 'svg', folder: 'svg' }The options to pass to Twemoji when using the Twemoji style. For a list of valid options, see the Twemoji documentation.
zIndexnumbernoneIf specified, sets the Z-index for the emoji picker element.

Method: destroyPicker()

Destroys the picker and removes it from the DOM. You will no longer be able to show the picker after it is destroyed.

Method: hidePicker()

Hides the picker.

Method: isPickerVisible()

Returns true if the picker is currently visible, false if not.

Method: off(event, callback)

Removes the given listener for the given event. See Events for a list of valid events.

Method: on(event, callback)

Adds a listener for the given event. See Events for a list of valid events.

Method: showPicker(referenceElement)

Shows the picker, positioning it relative to the given referenceElement.

Method: togglePicker(referenceElement)

Shows the picker (positioning it relative to referenceElement) if it is hidden, and hides it if it is visible.

Method: setTheme(theme)

Sets the theme of the picker. See Themes for more details.

Category IDs

The valid category IDs are as follows:

  • 'smileys'
  • 'people'
  • 'animals'
  • 'food'
  • 'activities'
  • 'travel'
  • 'objects'
  • 'symbols'
  • 'flags'

Icon Definition Objects

An icon definition object must contain at least one of the following properties:

  • search: The search icon, displayed when there is no search text entered.
  • clearSearch: The button to clear the search, displayed when there is search text entered.
  • notFound: The icon to display when a search yields no results.
  • categories: A nested object containing one or more of the following:
    • recents: The Recent Emojis category.
    • smileys: The Smileys & Emotion category.
    • peopls: The People & Body category.
    • animals: The Animals & Nature category.
    • food: The Food & Drink category.
    • activities: The Activities category.
    • travel: The Travel & Places category.
    • objects: The Objects category.
    • symbols: The Symbols category.
    • flags: The Flags category.
    • custom: The Custom category.

I18N Strings

The strings in the picker UI can be replaced with translated versions, if desired, by specifying the i18n option. The values and their defaults are as follows:

    search: 'Search emojis...',
    categories: {
      recents: 'Recent Emojis',
      smileys: 'Smileys & Emotion',
      people: 'People & Body',
      animals: 'Animals & Nature',
      food: 'Food & Drink',
      activities: 'Activities',
      travel: 'Travel & Places',
      objects: 'Objects',
      symbols: 'Symbols',
      flags: 'Flags',
      custom: 'Custom'
    notFound: 'No emojis found'