Discourse

A theme component: emoji by meaning in the composer, chat and the emoji picker.

On this page

A Discourse theme component: emoji by meaning in the composer (Markdown and rich text), in chat and in the emoji picker’s search. Emojisense ranks the emoji, and Discourse’s own matches fill the rest of the list.

“:ship it”🚀
“:mind blown”🤯
“:pizza”🍕

The packs ship as theme assets and load from the site the first time someone types : or searches the picker. Out of the box, no search text leaves the browser.

Install

In Admin → Appearance → Themes and components, choose Install → From a git repository and enter https://github.com/emojisense/discourse-emojisense. Then add the component to your site’s themes. It works on self-hosted sites and on Discourse-hosted plans that allow theme components.

Terminal

pnpm install && pnpm data:build             # once, from the repository root
pnpm --filter @emojisense/discourse build          # → apps/discourse/dist/theme
tar -czf emojisense-theme.tar.gz -C apps/discourse/dist theme

What changes

Where	What
Composer	`:` autocomplete ranked by meaning, also for phrases with spaces (`:ship it`) and letters outside ASCII (`:çay`), in the Markdown and the rich text editor
Chat	The same `:` autocomplete in the chat composer
Emoji picker	The search box ranks by meaning
Custom emoji	The site’s custom emoji join the results by their names: `:party parrot` finds `:party_parrot:`
Unchanged	Favorites (a bare `:`), skin tones (`:wave:t3`), text smileys (`:)`) and the user’s skin tone choice stay Discourse’s

Settings

Setting	Default	Notes
`search_locale`	`auto`	Each user’s interface language; English when Emojisense has no data for it
`culture`	On	Cultural and seasonal emoji after the best match. Regional entries follow the region of each user’s device (its language, else its time zone), read in the browser and never sent.
`api_enabled`	Off	Ask the Emojisense API when the dictionary is unsure
`publishable_key`	—	A `pk_live_…` key with the site’s address in its allowed origins. Theme settings are public: never a secret key.
`api_url`	`https://api.emojisense.com`

Compatibility

Discourse has no emoji search API for themes, so the component wraps three internal methods: the composer’s and the chat composer’s emoji autocomplete, and the picker’s search. A Discourse update can change them. When the packs have not loaded, or something fails, Discourse’s own search answers. Tested on Discourse 2026.10.