---
title: "Emoticons plugin"
description: "Bring a smiley to your content."
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/emoticons/"
md_url: "https://www.tiny.cloud/docs/tinymce/7/emoticons/index.md"
version: "7"
last_updated: "2024-05-22T07:03:35Z"
tokens: 1630
---
Important This page documents TinyMCE 7. For new projects, Tiny recommends using the latest, most up-to-date version. [See TinyMCE 8 documentation](../../latest/emoticons/).
# Emoticons plugin

This plugin adds a dialog to the editor that lets users insert emoji into TinyMCE’s editable area. The dialog can be invoked via a toolbar button - `emoticons` - or a dedicated menu item added as `Insert > Emojis...`.

The emoticons plugin provides an autocompleter for adding emoji without using the toolbar button or menu item. Adding a colon `:`, followed by at least two characters will open a popup collection showing matching emoji.

> **Note:** The emoticons plugin does not automatically convert text emoticons into graphical emoji.

## Basic setup

```js
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'emoticons',
  toolbar: 'emoticons'
});
```

## Browser emoji support

By default, the emoticon plugin inserts Unicode character codes, such as `\ud83d\ude03` for the smiley emoji. How emoji are rendered is dependent on the web browser and operating system of the user. As a result of this, some emoji may be rendered in black and white, or may not render. To ensure emoji render consistently across browsers and operating systems, Tiny recommends adding an emoji-compatible web font to the default font-family using [`content_css`](../add-css-options/#content_css).

**Example**

```js
tinymce.init({
  selector: 'textarea#emoticons',
  height: 300,
  plugins: 'lists code emoticons',
  toolbar: 'undo redo | styles | bold italic | ' +
    'alignleft aligncenter alignright alignjustify | ' +
    'outdent indent | numlist bullist | emoticons',
  emoticons_append: {
    custom_mind_explode: {
      keywords: ['brain', 'mind', 'explode', 'blown'],
      char: '🤯'
    }
  },
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});
```

## Options

The default database of emoji can be overridden or extended through the options below.

Internally, emojis are defined by an object mapping emoji names to additional details, whereby each entry represents a single emoji. The additional details should contain a unicode character representing the emoji, any keywords that can be used to search for the emoji and a category to place the emoji in. Options are expected to be provided in the same format.

```js
{
  robot: {
    keywords: [ 'computer', 'machine', 'bot' ],
    char: '🤖',
    category: 'people'
  },
  dog: {
    keywords: [ 'animal', 'friend', 'nature', 'woof', 'puppy', 'pet', 'faithful' ],
    char: '🐶',
    category: 'animals_and_nature'
  }
}
```

### `emoticons_append`

This option provides a way to append some additional emoji to the default emoji database. This should be an object in the above mentioned format.

**Type:** `Object`

#### Example: using `emoticons_append`

```js
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'emoticons',
  toolbar: 'emoticons',
  emoticons_append: {
    custom_mind_explode: {
      keywords: [ 'brain', 'mind', 'explode', 'blown' ],
      char: '🤯'
    }
  }
});
```

### `emoticons_database`

This option provides the ability to specify which built-in emoji database to use when rendering emojis in the editor. The following built-in emoji databases are available:

- `emojis` - This database uses Unicode characters to represent emoji in the editor content.
- `emojiimages` - This database uses images provided by the Twitter Emoji (twemoji) project to represent emoji in the editor content.

> **Important:** The emojiimages database provided by Tiny Technologies, Inc. uses Twitter Emoji (twemoji) graphics under the CC-BY 4.0 license agreement.
**Type:** `String`

**Default value:** `'emojis'`

#### Example: using `emoticons_database`

```js
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'emoticons',
  toolbar: 'emoticons',
  emoticons_database: 'emojiimages'
});
```

### `emoticons_database_url`

This option provides the default location to load the emoji database from. The database should be an external JavaScript file, that registers a `tinymce.plugins.emoticons` resource.

**Type:** `String`

**Default value:** `'${pluginUrl}/js/emojis.js'`

```js
tinymce.Resource.add('tinymce.plugins.emoticons', {
  robot: {
    keywords: [ 'computer', 'machine', 'bot' ],
    char: '🤖',
    category: 'people'
  }
});
```

#### Example: using `emoticons_database_url`

```js
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'emoticons',
  toolbar: 'emoticons',
  emoticons_database_url: '/emojis.js'
});
```

### `emoticons_images_url`

This option sets the base URL for the images used to represent emojis when using the `emojiimages` database.

By default, this option loads the required image *assets* from the Twemoji CDN. To use self-hosted emoji images, download the image *assets* from the [Twitter Emoji (Twemoji) GitHub repository](https://github.com/jdecked/twemoji/#download).

**Type:** `String`

**Default value:** `'https://cdnjs.cloudflare.com/ajax/libs/twemoji/15.1.0/72x72/'`

#### Example: using `emoticons_images_url`

```js
tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'emoticons',
  toolbar: 'emoticons',
  emoticons_database: 'emojiimages',
  emoticons_images_url: 'http://my.server/images/emoticons/'
});
```

## Toolbar buttons

The Emoticons plugin provides the following toolbar buttons:

| Toolbar button identifier | Description |
| --- | --- |
| `emoticons` | Opens the Emojis dialog. |

These toolbar buttons can be added to the editor using:

- The [`toolbar`](../toolbar-configuration-options/#toolbar) configuration option.
- The [`quickbars_insert_toolbar`](../quickbars/#quickbars_insert_toolbar) configuration option.
- [Custom Context toolbars](../contexttoolbar/).

## Menu items

The Emoticons plugin provides the following menu items:

| Menu item identifier | [Default Menu Location](../menus-configuration-options/#example-the-tinymce-default-menu-items) | Description |
| --- | --- | --- |
| `emoticons` | Insert | Opens the Emojis dialog. |

These menu items can be added to the editor using:

- The [`menu`](../menus-configuration-options/#menu) configuration option.
- The [`contextmenu`](../menus-configuration-options/#contextmenu) configuration option.
- [Custom Menu toolbar buttons](../custom-menu-toolbar-button/).

## Commands

The Emoticons plugin provides the following TinyMCE command.

| Command | Description |
| --- | --- |
| mceEmoticons | Opens the Emojis dialog. |

Example
```js
tinymce.activeEditor.execCommand('mceEmoticons');
```