Emoji Button

https://emoji-button.js.org
Admin
Emoji Button is a vanilla JavaScript emoji picker component that displays a customizable panel of...
Tokens:7,872
Snippets:137
Trust Score:8.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Emoji Button with npm or Yarn

Source: https://emoji-button.js.org/docs

Install the Emoji Button package using either npm or Yarn. This is the first step to using the component in your project.

```bash
# Using npm
npm install @joeattardi/emoji-button

# Using yarn
yarn add @joeattardi/emoji-button
```

--------------------------------

### Internationalization (i18n) Options

Source: https://emoji-button.js.org/docs/api

Customize UI strings for different languages by providing an `i18n` object during initialization. This example shows the default values for search, categories, and not found messages.

```javascript
{
    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'
  }
```

--------------------------------

### Import Custom Emoji Data

Source: https://emoji-button.js.org/docs/customData

Import emoji data from a specific locale package to use translated emoji names. Ensure the locale data package is installed.

```javascript
import { EmojiButton } from '@joeattardi/emoji-button';
import frEmojiData from '@roderickhsiao/emoji-button-locale-data/dist/fr';

const picker = new EmojiButton({
  emojiData: frEmojiData
});

```

--------------------------------

### Handle Emoji Selection Event

Source: https://emoji-button.js.org/docs/events

Listen for the 'emoji' event to get information about the selected emoji. The callback receives a selection object containing properties like 'emoji', 'name', and 'url'.

```javascript
const picker = new EmojiButton();

picker.on('emoji', selection => {
  alert(`"emoji" event fired, emoji is ${selection.emoji} with name ${selection.name}`);
});
```

--------------------------------

### Add a Custom Plugin to Emoji Button

Source: https://emoji-button.js.org/docs/plugins

This example demonstrates how to create a custom plugin that adds a 'Remove' button to the emoji picker. Clicking this button clears the selected emoji from a target element and hides the picker. Ensure the target element and the picker instance are correctly referenced.

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

const trigger = document.querySelector('#trigger');

const removePlugin = {
  render(picker) {
    const button = document.createElement('button');
    button.innerHTML = 'Remove';
    button.addEventListener('click', () => {
      trigger.innerHTML = '';
      picker.hidePicker();
    });

    return button;
  }
};

const picker = new EmojiButton({
  plugins: [removePlugin]
});

picker.on('emoji', selection => {
  trigger.innerHTML = selection.emoji;
});

trigger.addEventListener('click', () => picker.togglePicker(trigger));

```

--------------------------------

### Initialize with Light Theme

Source: https://emoji-button.js.org/docs/themes

Specify 'light' for the theme option to use the light theme. This is also the default behavior if no theme is specified.

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

const picker = new EmojiButton({
  theme: 'light'
});

```

--------------------------------

### Initialize with Dark Theme

Source: https://emoji-button.js.org/docs/themes

Specify 'dark' for the theme option to enable the dark theme for the emoji picker.

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

const picker = new EmojiButton({
  theme: 'dark'
});

```

--------------------------------

### Initialize with Automatic Theme

Source: https://emoji-button.js.org/docs/themes

Specify 'auto' for the theme option to have the emoji picker automatically adapt to the operating system's current theme setting.

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

const picker = new EmojiButton({
  theme: 'auto'
});

```

--------------------------------

### Switch Theme Dynamically

Source: https://emoji-button.js.org/docs/themes

Use the `setTheme` method on an existing EmojiButton instance to change the theme to 'light', 'dark', or 'auto' after initialization. Event listeners are shown for demonstration.

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

const picker = new EmojiButton();

document.querySelector('#set-theme-dark').addEventListener('click', () => picker.setTheme("dark"));
document.querySelector('#set-theme-light').addEventListener('click', () => picker.setTheme("light"));
document.querySelector('#set-theme-auto').addEventListener('click', () => picker.setTheme("auto"));

```

--------------------------------

### on

Source: https://emoji-button.js.org/docs/api

Adds an event listener to the emoji picker.

```APIDOC
## on(event, callback)

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

### Method
`on(event, callback)`

### Parameters
#### Path Parameters
- **event** (string) - Required - The name of the event to listen for.
- **callback** (function) - Required - The function to call when the event is triggered.
```

--------------------------------

### Initialize Emoji Picker in Vanilla JavaScript

Source: https://emoji-button.js.org/

Instantiate the EmojiButton class and attach it to a DOM element. This snippet requires the EmojiButton library to be imported.

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

const picker = new EmojiButton();
const trigger = document.querySelector('.trigger');

picker.on('emoji', selection => {
  trigger.innerHTML = selection.emoji;
});

trigger.addEventListener('click', () => picker.togglePicker(trigger));

```

--------------------------------

### Initialize Emoji Button with Twemoji Style

Source: https://emoji-button.js.org/docs/styles

Use this snippet to initialize the EmojiButton with the Twemoji style. This ensures a consistent emoji appearance across all platforms by using SVG images.

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

const trigger = document.querySelector('.trigger');

const picker = new EmojiButton({
  style: 'twemoji'
});

picker.on('emoji', selection => {
  // Remove the old image
  trigger.removeChild(trigger.firstChild);

  // Add the new image for the new Twemoji
  const img = document.createElement('img');
  img.src = selection.url;
  img.alt = selection.emoji + ' ' + selection.name;
  trigger.appendChild(img);
});

trigger.addEventListener('click', () => {
  picker.togglePicker(trigger);
});

```

--------------------------------

### EmojiButton Constructor

Source: https://emoji-button.js.org/docs/api

The EmojiButton class constructor allows for customization of the emoji picker through an options object. Below are the supported options.

```APIDOC
## EmojiButton(options)

### Description
Initializes a new instance of the EmojiButton class. Accepts an optional `options` object to configure the picker's behavior and appearance.

### Parameters
#### Options Object
- **autoHide** (boolean) - Optional - `true` - Whether or not the picker should be automatically hidden when an emoji is selected.
- **autoFocusSearch** (boolean) - Optional - `true` - Whether or not to automatically focus the search field when the picker is shown.
- **categories** (string array) - Optional - all categories - An array of the categories to include in the picker.
- **custom** (custom emoji definition array) - Optional - none - An array of custom emojis to add to the Custom category. Each element should have `name` and `emoji` properties.
- **emojiData** (object) - Optional - Built-in emoji data - Custom emoji data, typically for translated names.
- **emojiSize** (string) - Optional - `'1.8em'` - The size for emoji icons (e.g., CSS size expression).
- **emojisPerRow** (number) - Optional - `8` - The number of emojis to display per row.
- **emojiVersion** (string) - Optional - `'12.1'` - The version of the Emoji specification to use (e.g., '1.0', '12.1').
- **i18n** (object) - Optional - See I18N Strings - An object containing localized messages.
- **icons** (icon definition object) - Optional - none - Custom icons to use.
- **initialCategory** (string) - Optional - `'smileys'` - The ID of the category to show initially.
- **plugins** (plugin definition array) - Optional - none - An array of plugins to use with the picker.
- **position** (string or object) - Optional - `'auto'` - The position of the picker relative to the reference element.
- **recentsCount** (number) - Optional - `50` - The number of recent emojis to save.
- **rootElement** (HTML element reference) - Optional - `document.body` - The root DOM node to attach the picker element to.
- **rows** (number) - Optional - `6` - The number of visible rows in the picker.
- **showAnimation** (boolean) - Optional - `true` - Whether or not to show animations.
- **showCategoryButtons** (boolean) - Optional - `true` - Whether or not to show category buttons.
- **showPreview** (boolean) - Optional - `true` - Whether or not to show the preview area.
- **showSearch** (boolean) - Optional - `true` - Whether or not to show the search field.
- **showRecents** (boolean) - Optional - `true` - Whether or not to show and save recent emojis.
- **showVariants** (boolean) - Optional - `true` - Whether or not to support emoji skin tone variants.
- **style** (string) - Optional - `'native'` - The style for emojis ('native' or 'twemoji').
- **theme** (string) - Optional - `'light'` - The theme for the picker ('light', 'dark', or 'auto').
- **twemojiOptions** (object) - Optional - `{ ext: 'svg', folder: 'svg' }` - Options to pass to Twemoji.
- **zIndex** (number) - Optional - none - Sets the Z-index for the emoji picker element.
```

--------------------------------

### Provide Custom Search and Clear Search Icons

Source: https://emoji-button.js.org/docs/icons

Pass custom SVG paths for the search and clear search icons using the `icons` option when initializing the EmojiButton.

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

const picker = new EmojiButton({
  icons: {
    search: '/search.svg',
    clearSearch: '/close.svg'
  }
});
```

--------------------------------

### Import EmojiButton Class

Source: https://emoji-button.js.org/docs/api

Import the EmojiButton class from the @joeattardi/emoji-button module. This is the primary class for creating and managing emoji picker instances.

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

--------------------------------

### setTheme

Source: https://emoji-button.js.org/docs/api

Sets the visual theme of the emoji picker.

```APIDOC
## setTheme(theme)

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

### Method
`setTheme(theme)`

### Parameters
#### Path Parameters
- **theme** (string) - Required - The name of the theme to apply.
```

--------------------------------

### Initialize Emoji Button with Custom Emojis

Source: https://emoji-button.js.org/docs/custom

Configure Emoji Button to use custom image emojis by providing an array of objects to the `custom` property. Each object must have a `name` and an `emoji` property pointing to the image URL. When a custom emoji is selected, the `emoji` event will include `url` and `custom: true` properties.

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

const trigger = document.querySelector('#trigger');

const picker = new EmojiButton({
  custom: [
    {
      name: 'Conga parrot',
      emoji: './site/static/conga_parrot.gif'
    },
    {
      name: 'O RLY?',
      emoji: './site/static/orly.jpg'
    }
  ]
});

picker.on('emoji', selection => {
  trigger.removeChild(trigger.firstChild);

  if (selection.url) {
    const img = document.createElement('img');
    img.src = selection.url;
    img.alt = selection.emoji + ' ' + selection.name;
    trigger.appendChild(img);
  } else {
    const span = document.createElement('span');
    span.innerHTML = selection.emoji + ' ' + selection.name;
    trigger.appendChild(span);
  }
});

trigger.addEventListener('click', () => picker.togglePicker(trigger));

```

--------------------------------

### showPicker

Source: https://emoji-button.js.org/docs/api

Displays the emoji picker, positioning it relative to a specified element.

```APIDOC
## showPicker(referenceElement)

### Description
Shows the picker, positioning it relative to the given `referenceElement`.

### Method
`showPicker(referenceElement)`

### Parameters
#### Path Parameters
- **referenceElement** (HTMLElement) - Required - The element to position the picker relative to.
```

--------------------------------

### Hide UI Elements

Source: https://emoji-button.js.org/docs/customize

Create a minimal UI by selectively hiding elements like category buttons, search bar, preview pane, and recents using boolean options.

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

const picker = new EmojiButton({
  showCategoryButtons: false,
  showSearch: false,
  showPreview: false,
  showRecents: false
});
```

--------------------------------

### Fixed Picker Positioning

Source: https://emoji-button.js.org/docs/position

Configure fixed positioning by providing an object with `top`, `bottom`, `left`, or `right` properties to the `position` option. This allows precise placement on the screen.

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

const picker = new EmojiButton({
  position: {
    top: '0',
    right: '0'
  }
});

```

--------------------------------

### Set Initial Category

Source: https://emoji-button.js.org/docs/customize

Determine which emoji category is displayed when the picker first loads using the `initialCategory` option. Defaults to 'smileys'.

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

const picker = new EmojiButton({
  initialCategory: 'flags'
});
```

--------------------------------

### Relative Picker Positioning

Source: https://emoji-button.js.org/docs/position

Use the `position` option with a Popper.js placement string for relative positioning. This is useful when the picker should align with a reference element.

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

const picker = new EmojiButton({
  position: 'bottom-start'
});

```

--------------------------------

### Default I18N Strings Structure

Source: https://emoji-button.js.org/docs/i18n

Pass this object structure to the `EmojiButton` constructor to override default English strings. Ensure all expected keys are present for complete localization.

```javascript
{
    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'
}
```

--------------------------------

### Customize Picker Size

Source: https://emoji-button.js.org/docs/customize

Adjust the visual size of emojis, the number of emojis displayed per row, and the number of rows visible using `emojiSize`, `emojisPerRow`, and `rows` options respectively.

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

const picker = new EmojiButton({
  emojiSize: '64px',
  emojisPerRow: 4,
  rows: 4
});
```

--------------------------------

### Basic Emoji Button Usage

Source: https://emoji-button.js.org/docs

Integrate the Emoji Button component into your web page. A trigger element is required to toggle the picker. Listen for the 'emoji' event to handle selected emojis.

```html
<button class="trigger">Emoji</button>
```

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

const picker = new EmojiButton();
const trigger = document.querySelector('.trigger');

picker.on('emoji', selection => {
  // `selection` object has an `emoji` property
  // containing the selected emoji
});

trigger.addEventListener('click', () => picker.togglePicker(trigger));
```

--------------------------------

### off

Source: https://emoji-button.js.org/docs/api

Removes an event listener from the emoji picker.

```APIDOC
## off(event, callback)

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

### Method
`off(event, callback)`

### Parameters
#### Path Parameters
- **event** (string) - Required - The name of the event to remove the listener from.
- **callback** (function) - Required - The callback function to remove.
```

--------------------------------

### emoji event

Source: https://emoji-button.js.org/docs/events

This event is fired when an emoji is selected. The callback receives an object containing details about the selected emoji.

```APIDOC
## emoji event

### Description
Fired when an emoji is selected. The callback will receive a single object with one or more of the following properties:
  * `custom`: This will be `true` for a custom emoji.
  * `emoji`: The Unicode emoji character that was selected. This will be included for native and Twemoji emojis, but not for custom emojis.
  * `name`: The name of the emoji that was selected.
  * `url`: The URL of the emoji image. This will be included for Twemoji and custom emojis.

### Example
```javascript
const picker = new EmojiButton();

picker.on('emoji', selection => {
  alert(`"emoji" event fired, emoji is ${selection.emoji} with name ${selection.name}`);
});
```
```

--------------------------------

### hidePicker()

Source: https://emoji-button.js.org/docs/api

Hides the currently displayed emoji picker.

```APIDOC
## hidePicker()

### Description
Hides the emoji picker if it is currently visible.

### Method
`hidePicker()`
```

--------------------------------

### hidden event

Source: https://emoji-button.js.org/docs/events

This event is fired when the emoji picker is hidden.

```APIDOC
## hidden event

### Description
Fired when the picker is hidden.

### Example
```javascript
const picker = new EmojiButton();

picker.on('hidden', () => {
  alert('"hidden" event fired');
});
```
```

--------------------------------

### togglePicker

Source: https://emoji-button.js.org/docs/api

Toggles the visibility of the emoji picker, positioning it relative to a specified element.

```APIDOC
## togglePicker(referenceElement)

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

### Method
`togglePicker(referenceElement)`

### Parameters
#### Path Parameters
- **referenceElement** (HTMLElement) - Required - The element to position the picker relative to.
```

--------------------------------

### Specify Visible Categories

Source: https://emoji-button.js.org/docs/customize

Control which emoji categories are displayed by providing an array of category names to the `categories` option. The 'recents' category is included by default but can be hidden by setting `showRecents` to `false`.

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

const picker = new EmojiButton({
  categories: ['smileys', 'flags']
});
```

--------------------------------

### destroyPicker()

Source: https://emoji-button.js.org/docs/api

Destroys the emoji picker instance, removing it from the DOM and making it unusable.

```APIDOC
## destroyPicker()

### Description
Destroys the picker instance and removes its elements from the DOM. The picker cannot be shown after being destroyed.

### Method
`destroyPicker()`
```

--------------------------------

### Set Recent Emoji Count

Source: https://emoji-button.js.org/docs/recents

Configure the maximum number of recent emojis to save by setting the `recentsCount` property in the picker options. Defaults to 50.

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

const picker = new EmojiButton({
  recentsCount: 5
});
```

--------------------------------

### isPickerVisible

Source: https://emoji-button.js.org/docs/api

Checks if the emoji picker is currently displayed to the user.

```APIDOC
## isPickerVisible()

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

### Method
`isPickerVisible()`
```

--------------------------------

### Override CSS Variables

Source: https://emoji-button.js.org/docs/styleCustomization

Use the `styleProperties` option to override default CSS variables. This is useful for changing the font or element colors.

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

const picker = new EmojiButton({
  styleProperties: {
    '--font': 'Courier New',
    '--category-button-color': 'red'
  }
});

```

--------------------------------

### Handle Picker Hidden Event

Source: https://emoji-button.js.org/docs/events

Use the 'hidden' event to perform actions when the emoji picker is closed. This event does not pass any arguments to its callback.

```javascript
const picker = new EmojiButton();

picker.on('hidden', () => {
  alert('"hidden" event fired');
});
```

--------------------------------

### Set Emoji Specification Version

Source: https://emoji-button.js.org/docs/customize

Use the `emojiVersion` option to specify an older version of the Unicode Emoji specification if needed. Defaults to Emoji 12.1.

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

const picker = new EmojiButton({
  emojiVersion: '1.0'
});
```

--------------------------------

### Disable Emoji Variants

Source: https://emoji-button.js.org/docs/variants

To disable the emoji variant popup, set the `showVariants` option to `false` when initializing the EmojiButton. This prevents the variant selection UI from appearing.

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

const picker = new EmojiButton({
  showVariants: false
});
```

--------------------------------

### Disable Auto-Hide Picker

Source: https://emoji-button.js.org/docs/customize

Set `autoHide` to `false` to prevent the picker from automatically hiding when an emoji is selected. The picker will remain open until manually closed via `togglePicker`, `hidePicker`, or an external click.

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

const picker = new EmojiButton({
  autoHide: false
});
```

--------------------------------

### Hide Recent Emojis Category

Source: https://emoji-button.js.org/docs/recents

Prevent the Recent Emojis category from displaying by setting `showRecents` to `false` in the picker options. This is useful if you do not want to track or show recently used emojis.

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

const picker = new EmojiPicker({
  showRecents: false
});
```
Tokens:
Raw