# Configure custom emoji

**URL:** https://meta.discourse.org/t/configure-custom-emoji/23365
**Category:** Site Management
**Tags:** emoji, how-to, customization
**Created:** [February 3, 2019, 11:00pm UTC](https://meta.discourse.org/t/configure-custom-emoji/23365 "2019-02-03T23:00:00Z")
**Posts on this page:** 1
**Showing post:** 1

<div class="post-metadata">

### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [February 3, 2019, 11:00pm UTC](https://meta.discourse.org/t/configure-custom-emoji/23365/1 "2019-02-03T23:00:00Z")

</div>

> 🔖 This guide explains how to customize emojis on your Discourse site through selectable emoji sets, uploading new emoji, configuring site settings, and adjusting emoji sizes.
> 
> 🙋 Required user level: Administrator

## Selecting an emoji set

Discourse currently supports five emoji sets:

- Fluent UI
- Noto
- OpenMoji
- Twemoji
- Standard (Unicode)

For an overview on how the different sets look, you can take a look at [this emoji set comparison](https://www.supermathie.net/~michael/emoji.html). You can configure the `emoji_set` site setting at `/admin/config/emoji/settings` along with other emoji-related settings.

 ![image](https://global.discourse-cdn.com/meta/original/4X/d/6/2/d62fa1295384614966e8965317a8b5132b7036a7.png)

> [@](#):
>
> ℹ The dropdown also shows legacy sets that are no longer actively supported for licensing reasons. They remain listed for backwards compatibility - if your site used one of these sets, it will continue to work, but emojis will now display using the corresponding current set.
> 
> > **Table showing legacy sets and their fallbacks**
> >
> > | Legacy set | Fallback |
> > | --- | --- |
> > | Apple/International | Twemoji |
> > | Facebook Messenger | Standard (Unicode) |
> > | Google style | Noto |
> > | Google Classic | Noto |
> > | Twitter style | Twemoji |
> > | Win10 style | Fluent UI |

## Adding custom emoji

To add custom emoji:

1. Navigate to **Admin → Appearance → Emoji** at `/admin/config/emoji`

2. Click the Add emoji button to name, classify, and upload your emoji image  
ℹ If you have multiple emoji files to upload, you can select up to 10 image files in the file picker to bulk upload. The image filenames will be used as emoji names in this case.

## Bulk import custom emojis

You can import up to 1000 emojis via a single ZIP with an `emojis.csv` manifest. The CSV file must have the following columns with headers: `name`, `group`, `filename`.

```plaintext
name,group,filename
emoji_a,group_name,image.png

```

The import process relies entirely on the manifest. If file or row is missing, it will be skipped. The `group` field can be left empty, in which case the custom emoji will be added to the `default` group.

To import:

1. Navigate to **Admin → Appearance → Emoji** at `/admin/config/emoji`

2. Click the Import button, and select the ZIP file containing your emojis.

3. Preview the import and confirm changes. You can resolve any conflicts here by selecting which emoji to keep. Conflicts can occur if an existing emoji with the same name (and different group/image) already exists. To complete import, click Confirm import.  

## Bulk export custom emojis

Custom emojis can be exported in a single ZIP file. The resulting ZIP file will contain an `emojis.csv` manifest, ready to be imported to any Discourse site without modification. This contains the image, name, and group of each emoji.

To export, click on the Select to export button, and select all emojis you are exporting. When ready, click on the Export button, and a ZIP file will be downloaded.

 ![image](https://global.discourse-cdn.com/meta/original/4X/0/a/b/0ab5a97518c0d6d2cf845b4d4b5e39a5b8394b09.png)

 ![image](https://global.discourse-cdn.com/meta/original/4X/e/0/8/e0813b68437fd15650b6c99f1a0e9e82cc3c4deb.png)

## Pinning Emojis to the top of the picker

You can pin any emoji group to the top of the emoji picker. Access the setting `emoji_picker_pinned_groups` via **Admin → Appearance → Emoji → Settings** at `/admin/config/emoji/settings`. Input the name of the emoji group to be pinned to the top of the picker.

 ![image](https://global.discourse-cdn.com/meta/original/4X/1/6/6/166adcec260de79afa22b212344c9a5b364dd7b9.png)

 ![image](https://global.discourse-cdn.com/meta/original/4X/2/2/b/22ba4f9135b1e2e5daaa3f4ea47679acb91e5bc5.png)

Both custom and regular emoji groups can be pinned to the top. For example, inputting `flags` will move the flag emoji group to the top above smileys.

Names of default emoji groups:

- `smileys_&_emotion`
- `people_&_body`
- `animals_&_nature`
- `food_&_drink`
- `travel_&_places`
- `activities`
- `objects`
- `symbols`
- `flags`

## Emoji settings

You can access emoji settings at `/admin/config/emoji/settings` to customize how emojis behave on your site.

- `enable_emoji` - Enable the display and use of emojis in your Discourse instance. If disabled, emojis will not be rendered and users will not be able to access or use them in text fields.
- `emoji_set` - Select your preferred style of emoji. Different emoji sets can provide unique appearances to the emojis displayed on the site.
- `max_emojis_in_title` - Maximum allowed emojis in topic title (default: 1). If the set value is zero, it prevents the use of any emojis in topic titles.
- `enable_emoji_shortcuts` - Common smiley text such as `:)` `:p` `:(` will be converted to emojis.
- `emoji_autocomplete_min_chars` - Minimum number of characters required to trigger autocomplete emoji popup (default: 0).
- `enable_inline_emoji_translation` - Enables translation for inline emojis (without any space or punctuation before).
- `emoji_deny_list` - These emoji will not be available to use in menus or shortcodes.
- `emoji_picker_pinned_groups` - These emoji groups are pinned to the top of the emoji picker.
- `external_emoji_url` - URL of an external service for emoji images. Leave blank to use the default.
- `discourse_reactions_enabled_reactions` - Defines a list of enabled reactions, any emoji is allowed here. Default reactions: +1, laughing, open\_mouth, clap, confetti\_ball, and hugs.
- `discourse_reactions_excluded_from_like` - Reactions that do not count as a Like. Any reactions that are not on this list will count as a Like for badges, reporting, and other purposes.
- `discourse_reactions_allow_any_emoji` - If this is enabled, will add a button allowing users to select any emoji in the reactions picker. Members will be allowed to choose any emoji, including custom emoji, for reactions. To limit available reactions, use the `emoji_deny_list` site setting.

## Resizing custom emoji

By default, all emoji are resized via CSS to 20x20, but this can be overridden with custom CSS. To maintain the correct aspect ratio and native size in posts, add the following CSS:

```css
/* Make emoji normal size (don't force square) */
div.topic-post img.emoji[src*="uploads"], 
div.d-editor-preview img.emoji[src*="uploads"], 
div.emoji-modal img.emoji[src*="uploads"], 
div.d-editor-textarea-wrapper img.emoji[src*="uploads"], 
div.title-wrapper img.emoji[src*="uploads"], 
td.main-link img.emoji[src*="uploads"] {
  width: auto;
  height: auto;
}

```

To customize a specific emoji’s size, use:

```css
img.emoji[title=":youremoji:"] { 
  height: XXpx; 
  width: YYpx; 
}

```

For resizing emoji in chat messages and user status in chats:

```css
div.chat-message-text img.emoji[src*="uploads"], 
span.user-status-message img.emoji[src*="uploads"] {
  width: auto;
  height: auto;
}

```

> Last edited by @Alteras 2026-07-22T23:53:28Z
> 
> > **Check document**
> >
> > Perform check on document:

---

_[View the full topic](https://meta.discourse.org/t/configure-custom-emoji/23365)._