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 seven different emoji sets:

• Apple/International style
• Google style
• Twitter style
• Emoji One style
• Win10 style
• Google Classic
• Facebook Messenger

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.

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 @martin 2025-01-23T05:07:38Z

Check document

Perform check on document:

[Roi]

I noticed that the custom emojis/smileys show 20x20 in chat messages and in the user status in chats. I solved it that way:

div.chat-message-text img.emoji[src*="uploads"] { /* Chat messages */
    width: auto;
    height: auto;
}

span.user-status-message img.emoji[src*="uploads"] { /* User status in chat */
    width: auto;
    height: auto;
}

Would you do it that way, too? If yes, it might be useful to add it to this wiki post above. If not, I am happy to optimize my CSS code.

[Vladislav_Jandric]

I customized new Emoji, but I can t it find among another Emojis.

[ondrej]

Have you scrolled all the way down in the emoji picker? That’s where your custom emoji groups live.

[Moin]

@Discourse

Discourse comes with seven different emoji sets:

• Apple/International style
• Google style
• Twitter style
• Emoji One style
• Win10 style
• Google Classic
• Facebook Messenger

Those have changed:

Emojis update

For licensing reasons, we had to change the emoji sets. The following existing sets have been migrated automatically to a new set: apple → twemoji facebook_messenger → unicode google → noto google_classic → noto win10 → fluentui emoji_one → twemoji twitter → twemoji On top of fluent ui, noto, twemoji, and unicode, we also added the openmoji set. Admins can change the set at /admin/config/emoji/settings?filter=emoji_set If there’s an existing open-source set you would like to see available i…

[pacharanero (Marcus Baw)]

I’ve been trying some different options for Bulk Upload of Custom Emoji, but have drawn a blank so I’m asking here what the best future option would look like.

I have a small collection of custom emoji I like to upload into all my Discourses. Some are FontAwesome icons, which I like to have available as :icon-name: in composer posts so that I can explain Discourse UI icons to users. Others are just for fun like a Yorkshire flag. I have them in folders (and they could easily also be online in a GitHub repo I suppose).

I would like to be able to upload these entire folders, in one go, to the Custom Emoji UI. At present the limit on uploads respects the setting of simultaneous_uploads (‘Maximum number of files that can be dragged & dropped in the composer’) site setting, which is limited to a ceiling value of 20 (Error: “simultaneous_uploads: Value must be between 0 and 20.” if you try to increase it higher, even temporarily)

I investigated with interest the other Emoji setting external-emoji-url, which allows one to set a URL for external Emoji set, but sadly this replaces all the ‘standard’ emoji, which I don’t want to lose.

All I really need is for folder upload of custom emoji to work as it currently does for individual custom emoji. Alternatively if there was no limit to the number of uploads that were allowed (perhaps the upload job could be sent to SideKiq to be done async, and PM admins when it’s done, like for bulk invites)

I investigated the use of the Discourse REST API for this but Custom Emoji are not exposed via the REST API. Uploads are exposed in the API, and I did have this working, but even if using the custom_emoji type for an upload it doesn’t appear in the list.

Just wondering what the community thinks would be the best way forward:

• Rake task which automates bulk custom emoji creation?
• Do it in the Rails console?
• Change the admin UI upload limits to allow several hundred uploads in one shot?
• Add ‘folder upload’ to the admin UI?
• Make custom emoji something that I could deploy as a Theme Component which I could add from GitHub URL? (I like the simplicity of this one)
• Allow multiple External emoji URLs so I can have an emoji set AND my custom emoji (perhaps served from a GitHub pages repo)
• Hack together a single ‘emoji and custom emoji’ repo which I can address via URL?

OR - is there another way to get all the FontAwesome icons that Discourse uses in its UI to be available in the composer using :icon-name: syntax? Really the majority of what I want to do is related to this. A site setting that enabled UI icons to be available in the composer would get me 90% there.

[JammyDodger]

@pacharanero

Really the majority of what I want to do is related to this. A site setting that enabled UI icons to be available in the composer would get me 90% there.

I have used the Discourse Icon theme component for a similar use case, if that’s any help?

Example from the topic:

This is the [wrap=icon id=far-square][/wrap] icon and the [wrap=icon id=pencil][/wrap] icon.

This is the icon and the icon.

[pacharanero (Marcus Baw)]

Thanks @JammyDodger that’s helpful and definitely an option I would consider, even though the UX of the [wrap=icon id=icon-name][/wrap] syntax is not as nice as :icon-name:.

A downside of the Discourse Icon approach is that I have to manually add a list of all the icons I want to use in the svg icon subset site setting. But at least that can be done in one go by copy-pasting from a list in a text file.

[Moin]

@pacharanero

explain Discourse UI icons to users

From your description, I wouldn’t expect you to have to add that much. The setting is to add more icons. All icons that are used in the forum are already available.

[pacharanero (Marcus Baw)]

@Moin

All icons that are used in the forum are already available.

Where are they available? I welcome it, if they are. But I can’t seem to access them with the :icon-name: type syntax.

I just want to easily be able to tell people, for example, that to add a timezone-aware datetime to a post they use the :calendar-days: button in the Composer toolbar. But when I search the included emoji/icons the nearest thing I can get is .

[Moin]

They work with the wrap syntax and Discourse icon without adding them to svg icon subset.

The answer referred to your comment that it is a disadvantage that you have to add all the icons.

@pacharanero

A downside of the Discourse Icon approach is that I have to manually add a list of all the icons I want to use in the svg icon subset site setting.

---

Maybe it would work to use watched-words to replace :calendar-days: with [wrap=icon id=calendar-days][/wrap]

[pacharanero (Marcus Baw)]

@Moin

They work with the wrap syntax and Discourse icon without adding them to svg icon subset.

The answer referred to your comment that it is a disadvantage that you have to add all the icons.

Ah OK, thanks and apologies for my misunderstanding. This is awesome. So I can use anywhere using wrap syntax! Every day is a Discourse school day!

The only missing part is the ability to easily search for the Discourse name of the icon I need, but I guess I can always use the browser inspector to find the d-icon- name and adjust accordingly. Or the FontAwesome website.

Thanks @Moin