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. You can configure the emoji_set site setting at /admin/config/emoji/settings along with other emoji-related settings.
Adding custom emoji
To add custom emoji:
-
Navigate to Admin → Appearance → Emoji at
/admin/config/emoji -
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.
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:
-
Navigate to Admin → Appearance → Emoji at
/admin/config/emoji -
Click the Import button, and select the ZIP file containing your emojis.
-
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.
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.
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_&_emotionpeople_&_bodyanimals_&_naturefood_&_drinktravel_&_placesactivitiesobjectssymbolsflags
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 theemoji_deny_listsite 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:
/* 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:
img.emoji[title=":youremoji:"] {
height: XXpx;
width: YYpx;
}
For resizing emoji in chat messages and user status in chats:
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: