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.
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. -
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 @tshenry 2026-03-24T23:29:45Z
Check document
Perform check on document: