How to Add a Custom Emoji to a Mastodon Display Name

Mastodon lets you add a custom emoji to your display name. This is different from standard Unicode emoji. Custom emoji are uploaded by instance administrators and can be used by anyone on that server. They appear as small images next to your name in posts, profiles, and timelines. This article explains how to find, add, and use custom emoji in your Mastodon display name.

What Are Custom Emoji in Mastodon?

Custom emoji are small image files uploaded by the administrators of a Mastodon instance. They are not part of the Unicode standard. Each custom emoji has a shortcode, which is a word or phrase surrounded by colons, such as :blobcat: or :mastodon:. When you type the shortcode in a post or in your display name, Mastodon replaces it with the corresponding image.

Custom emoji are instance-specific. If you are on instance A, you can only use the custom emoji that instance A has uploaded. If you move to instance B, you will see a different set of custom emoji. Some instances have hundreds of custom emoji, while others have very few. You can usually view the full list by going to https://[your-instance]/about/more and scrolling to the custom emoji section.

How Custom Emoji Differ From Unicode Emoji

Unicode emoji are standard across all platforms. They look the same on Mastodon, Twitter, or any other app. Custom emoji are unique to the instance. They can be any image, including animated GIFs. Unicode emoji are typed using the system emoji picker on your device. Custom emoji require you to type the shortcode manually or select them from the emoji picker in Mastodon’s composer.

Prerequisites for Using Custom Emoji in Your Display Name

You need a Mastodon account on an instance that has custom emoji uploaded. Most public instances have at least a few. You also need to know the exact shortcode of the emoji you want to use. You can find shortcodes by looking at the custom emoji list on your instance or by clicking an emoji in the composer picker and noting the code that appears.

Steps to Add Custom Emoji to Your Mastodon Display Name

Follow these steps to add a custom emoji to your display name. The process works the same on Mastodon web and most mobile apps.

1. Open your profile settings
   On the Mastodon web interface, click the gear icon in the bottom-left corner of the main column. This opens the Preferences menu. On mobile, tap the hamburger menu and select Preferences.
2. Go to Appearance settings
   In the Preferences menu, click Appearance in the left sidebar. This section controls how your profile looks to others.
3. Locate the Display name field
   Scroll down to the Profile section. The first field is Display name. This is where you type the name you want others to see.
4. Type your display name with the emoji shortcode
   Type your desired display name. Where you want the emoji to appear, type the shortcode surrounded by colons. For example, if the shortcode is :blobcat:, type My Name :blobcat:. You can place the shortcode at the beginning, middle, or end of the name.
5. Save your changes
   Scroll to the bottom of the Appearance page and click the Save changes button. The page will reload. Your display name now shows the custom emoji image next to the text.

After saving, your new display name appears immediately on your profile and in your posts. Other users on the same instance will see the custom emoji. Users on other instances may see the shortcode text instead if their instance does not have that emoji.

Common Mistakes and Things to Avoid

Using a Shortcode That Does Not Exist on Your Instance

If you type a shortcode for an emoji that does not exist on your instance, Mastodon will display the raw shortcode text (for example, :nonexistent:) instead of an image. Always verify the shortcode by checking the custom emoji list on your instance.

Mixing Custom Emoji With Unicode Emoji

You can mix custom emoji with Unicode emoji in your display name. However, Unicode emoji are typed using your device’s emoji keyboard, not with colons. If you type a Unicode emoji character directly into the display name field, it will display as a standard emoji. If you type a colon-wrapped code that is not a custom emoji, it will not convert.

Custom Emoji Not Displaying for Users on Other Instances

When you use a custom emoji in your display name, it only displays as an image for users on the same instance. Users on other instances will see the shortcode text in brackets, such as :blobcat:, unless their instance also has that exact emoji with the same shortcode. This is a limitation of Mastodon’s federation model.

Display Name Character Limit

Mastodon limits display names to 30 characters. Each shortcode counts as the number of characters it contains, not as one character. For example, :blobcat: is 9 characters. Keep your display name short enough to fit the emoji shortcode within the limit.

Custom Emoji in Display Name vs Unicode Emoji

Item	Custom Emoji	Unicode Emoji
Source	Uploaded by instance administrator	Part of the Unicode standard
Appearance	Image file, can be animated	Vector glyph, static
How to insert	Type shortcode like :blobcat:	Use system emoji picker or paste character
Visible to other instances	Only if they have the same emoji	Always visible as standard emoji
Character count	Counts as the number of characters in the shortcode	Counts as one character

Custom emoji give your display name a unique look that reflects the culture of your instance. Unicode emoji are more portable across instances. Choose based on whether you want instance-specific flair or universal compatibility.

You can now add custom emoji to your Mastodon display name using shortcodes. Start by checking your instance’s custom emoji list to find shortcodes you like. Remember that the emoji only appears as an image for users on your instance. For a more portable option, consider using Unicode emoji instead. If you want to suggest new custom emoji for your instance, contact your instance administrator.