Custom Emoji on Mastodon

This morning I made an :indieHeart: custom emoji for Mastodon. Here are some things I learned.

screenshot of the Mastodon admin showing my local instance’s custom emoji including two Indie heart emojis.

One of the many cool features of Mastodon is that you can create custom emoji for your instances which can be duplicated and adopted by other instances.

a toot in the dark Mastodon theme with a little Indie heart emoji. the same toot in the light Mastodon theme with a little Indie heart emoji.

The :indieHeart: shortcode in action

  • Firstly, you need to have admin access to your instance to add custom emoji. (Another reason to get your own instance!) If you don’t have admin access, you could probably politely ask your instance’s admin to add your emoji to the instance’s list.
  • You need to be able to tell what the emoji is at 20x20 pixels, as this is the standard size it’s displayed on the Mastodon web view.
  • The emoji could be displayed on any colour background as different Mastodon themes have different coloured backgrounds. If you’re looking for compatibility with the (current) default Mastodon themes, check your emoji graphic with these hex colours as backgrounds: #1F232B, #282C37, #D9E1E8, #E6EBF0, #FFFFFF.
  • Make the bounding box square, even if your graphic is tall and narrow. It looks like some apps might render all emoji as the same height and width, so this will avoid your emoji looking stretched or squashed.
  • The 50KB limit for emoji files is fairly high for a simple shape, so you can afford to scale your image up to be pretty big (the indieHeart is 520x520px) so it looks sharp on screens with a higher resolution.
  • Thickening lines in the graphic will make them look better when the emoji is scaled down very small, as it will increase the contrast and visibility of the lines, particularly on higher resolution screens where fine lines can appear very thin.
  • You need to post a toot with the emoji shortcode in it on your own instance before it becomes available to copy by other instances.

Lastly, but importantly: the macOS screenreader VoiceOver reads “indie underscore heart, image” for :indie_heart: and “indie heart, image” for :indieHeart:.

So while word_word or wordword seems to be the standard for multiple-word emoji on Mastodon, using camel case is probably more accessible.