Configure custom emoji

[Discourse]

This guide explains how to configure custom emojis on your Discourse site.

Required user level: Administrator

Configuring custom emoji

Want to change emoji for your Discourse site? Let’s take a look at how to configure custom emoji for your Discourse site, including selecting emoji sets, uploading new emoji, and adjusting emoji sizes.

Selecting an emoji set

Discourse comes with eleven different emoji sets:

• Apple/International style
• Facebook Messenger
• Fluent UI
• Google style
• Google Classic
• Noto
• OpenMoji
• Twemoji
• Twitter style
• Standard (Unicode)
• Win10 style

You can select an emoji set at /admin/config/emoji/settings?filter=emoji%20set along with other emoji-related settings.

Adding custom emoji

To add custom emoji:

1. Navigate to: Discourse Admin - Config - Emoji at /admin/config/emoji
2. You can:
   • Enter a name and click Add emoji to upload a photo as an emoji
   • Drag and drop up to 10 files into the Name field to bulk upload; filenames will be used as emoji names.

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 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:

/* 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 @SaraDev 2025-12-03T21:53:33Z

Check document

Perform check on document: