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';

`EmojiButton(options)`

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

Supported options are:

Name	Type	Default	Description
`autoHide`	boolean	`true`	Whether or not the picker should be automatically hidden when an emoji is selected.
`autoFocusSearch`	boolean	`true`	Whether or not to automatically focus the search field when the picker is shown.
`categories`	string array	all categories	An array of the categories to include in the picker. See Category IDs for a list of valid values.
`custom`	custom emoji definition array	none	An 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.
`emojiData`	object	Built-in emoji data	The custom emoji data to use. This is typically used for providing translated emoji names, such as from the @roderickhsiao/emoji-button-locale-data package.
`emojiSize`	string	`'1.8em'`	The size to use for the emoji icons. This can be any valid CSS size expression.
`emojisPerRow`	number	`8`	The 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`.
`emojiVersion`	string	`'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'`
`i18n`	object	See I18N Strings.	An object containing localized messages to display in the UI. See I18N Strings for the object format and default values.
`icons`	icon definition object	none	The 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.
`initialCategory`	string	`'smileys'`	The ID of the category to show initially when the picker is shown. See Category IDs for a list of valid category IDs.
`plugins`	plugin definition array	none	An 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.
`position`	string 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.
`recentsCount`	number	`50`	The number of recent emojis to save.
`rootElement`	HTML element reference	`document.body`	The root DOM node to attach the picker element to.
`rows`	number	`6`	The number of visible rows in the picker.
`showAnimation`	boolean	`true`	Whether or not to show animations in the picker.
`showCategoryButtons`	boolean	`true`	Whether or not to show the category buttons. If `emojisPerRow` is 6 or less, it is recommended to set this to `false`.
`showPreview`	boolean	`true`	Whether or not to show the preview area.
`showSearch`	boolean	`true`	Whether or not to show the search field.
`showRecents`	boolean	`true`	Whether or not to show (and save) recently selected emojis.
`showVariants`	boolean	`true`	Whether or not to support emoji skin tone variants.
`style`	string	`'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.
`theme`	string	`'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.
`twemojiOptions`	object	`{ 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.
`zIndex`	number	none	If 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'
  }

API Documentation

EmojiButton Class

EmojiButton(options)

Method: destroyPicker()

Method: hidePicker()

Method: isPickerVisible()

Method: off(event, callback)

Method: on(event, callback)

Method: showPicker(referenceElement)

Method: togglePicker(referenceElement)

Method: setTheme(theme)