decomoji ships thousands of text-drawn Slack emoji and a script to install them

An emoji set where every image is a rendered piece of text

decomoji is a collection of custom emoji for Slack reactions, described in the README as an image file with text written into it, with attention paid to abbreviations, character density and a sense of fun. The project calls each one a decomoji, and the repository is on its fifth major version.

The design constraints are worth stating because they explain the whole collection. There is a palette of twelve colours chosen to stay legible against the Slack interface, and the palette was adjusted so the images still read on a dark background, which the README describes as a feature rather than an afterthought. The layout is the work of a craftsman, laid out mostly on two lines, and expanding to three to five lines when a phrase is long. The README puts the total at roughly twenty thousand emoji across the collection.

What you get is therefore a visual language rather than a set of pictograms. An ordinary emoji set gives you a face, an animal or an object. decomoji gives you short phrases rendered as images, which means a reaction can carry a sentence, a meme reference or a piece of internal jargon, and it looks the same in every channel because the artwork is identical everywhere.

The stated purpose is that decomoji brings culture and velocity to your workspace. That is the marketing line, and the concrete version of it is that a reaction becomes a sentence you can type at speed.

The collection is credited to imaz, whose :naruhodo: custom emoji inspired it, along with a long list of named contributors.

Three categories, and one of them is deliberately quarantined

The set is divided into three categories, and the split is not only organisational.

The basic set holds 300 emoji and is the recommended starting point. The README tells you to register those first and use them for a while before adding anything else, which is sensible advice for a collection this size since you cannot undo the effect on a whole workspace at once.

The extension set exists for when the basic set stops feeling like enough, and it is where the bulk of the twenty thousand lives.

The third category is the explicit set, which isolates content that is sexual, violent or otherwise explicit and requires care when used. The README is blunt about it: in many cases it is better not to use it. Notably, the migration mode does not register this set at all.

The lists themselves live in the docs directory as basic and extra listings, and the README warns you before you open them, because the documentation page transfers a very large number of image files over the network.

A separate finder site at finder.decomoji.dev addresses the practical problem of a collection this size, which is that you cannot remember whether the phrase you want already exists. It supports regular expression search, and the README links it with a size and category parameter for the basic set.

Registering by script needs a workspace admin and Node.js 18.16

There are three ways to get decomoji into a workspace, and the README lists them in order of increasing effort: one at a time through the emoji registration form, by drag and drop with the Slack Custom Emoji Manager Chrome extension, or in bulk from the command line with the bundled script.

The script path is the one the project documents in detail, and the README flags it as for engineers. It requires Node.js v18.16.0, and the steps are a clone, an install and a run.

git clone [email protected]:decomoji/decomoji.git
cd decomoji
npm ci
node scripts/manager/index.mjs

The command runs an interactive session. You enter the workspace, the account, the password, whether you are registering or deleting, and which target types to process, and the script takes over from there.

The credentials are the part to think about. The script asks for your account and password directly, and it drives the Slack emoji page, which means it needs a browser and a real session. The dependency list supports that reading: puppeteer is a dev dependency alongside inquirer for the prompts and commander for argument parsing. The package.json exposes the same entry point as a script named manager.

  "scripts": {
    "manager": "node scripts/manager/index.mjs -lt"
  },

Two consequences follow. First, entering a password into an interactive script that automates a browser is a credential exposure decision, and you should make it knowingly. Second, the README says that if you use 2FA login the process can take hours, and recommends disabling 2FA first if you can. That is a concrete instruction about the login path, and it tells you the script has no good way to supply a one-time code in a loop.

On the flip side, the repository is built for image work. The dev dependencies include imagemin with optipng and pngquant plugins, plus email-validator and date-fns, and the allowScripts block enables the native binaries for optipng, pngquant and puppeteer.

Delete strength is the setting that can hurt someone else

The script exposes a set of modes, and the choices are more consequential than a usual command line tool.

The basic modes are adding, deleting, registering aliases, migrating from v4 to v5, and updating to the latest v5. You then choose what to process: by category, meaning the basic set, the extension set or the explicit set, or by version, meaning each v5.x.y release in turn. The version granularity exists so you can process only what changed after a specific point, and the README gives a concrete example: if you know you registered up to v5.9.0, choose the by-version target and select v5.9.1 onwards. That is faster than reprocessing a whole category and it skips anything fixed or added before your cut-off.

Then there is the strength setting, and it applies to deletion, migration and update.

In strong mode the script deletes everything matching the target, up to what the permissions allow. In weak mode it deletes only the decomoji you added yourself. The difference matters in a shared workspace: strong mode can remove emoji that a colleague uploaded and that the team has come to rely on, and there is no undo described in the documentation.

The migration mode is the one with the most moving parts, and it is worth reading before running it. It deletes all the v4 era decomoji, registers the new v5 ones, and registers aliases from old file names to new ones so that existing messages still resolve to the right image. It processes the basic and extension sets, deletes the explicit v4 emoji, and does not register the v5 explicit set.

Two update paths with different preconditions

The v5 update mode is narrower than the migration mode and has an explicit precondition: you must already have at least v5.0.0 registered.

Running it deletes the decomoji that were missing as of v5.0.0 onwards, registers the emoji of the selected target types, and registers aliases for decomoji whose file names were corrected after v5.0.0. As with the migration mode, the target type selection decides the scope. Choosing a category processes every emoji in that category, while choosing a version extracts and processes only the ones that were fixed, added or renamed in that version.

Both modes start the same way, with a git pull to bring the repository up to date. That is worth noting because it means the update path depends on the git checkout rather than on a published package version, even though the repository publishes npm releases. The package.json version is 5.35.0 and the last release was v5.35.0 on 2026-09-09, with v5.34.1 on 2026-07-18 and v5.33.1 on 2026-04-26. The last push to the repository was on 2026-10-05.

The repository layout supports the split between artwork and tooling. There is a decomoji directory holding the images, a configs directory, a scripts directory with the manager, and a docs directory with the lists, the advanced management guide, the contributing guidelines, the file naming conventions and the changelog.

The licensing is straightforward: MIT, with the copyright held by the decomoji consortium and other contributors since 2015.

Where decomoji is the wrong tool

The first limitation is the one the project itself names. Registering custom emoji requires permission, so a workspace where only administrators can add custom emoji rules this out for most people. The README says this in bold right at the start of the registration section, which suggests it is the most common failure point.

The second is scale. Twenty thousand emoji is a lot of images to push into a workspace through a browser automation flow, and the README's own advice is to start with 300. Even the basic set is a substantial upload, and the list documentation page transfers a large number of image files over the network.

The third is the credential handling. You give a script your Slack account and password, and if you rely on 2FA the README warns the process can take hours and suggests turning 2FA off first. Turning off 2FA for a bulk emoji upload is a poor trade for most organisations, and this is the clearest sign that the tool is built for a specific culture of use rather than for a general audience.

The fourth is that this is a Slack asset set, not a design system. The images have a house style with a fixed twelve colour palette and a specific layout rhythm, and they are drawn as text in a particular aesthetic. If you want emoji that match your brand's own typeface and palette, decomoji is not a source you can restyle, only one you can install or not.

How it compares to the one-off registration route

The alternative is registering emoji by hand through the Slack emoji form, or by dragging files in with the Chrome extension, and neither requires you to hand over a password to a script.

That is the entire difference in approach. The manual route is slow but bounded: you upload only what you chose, you see each upload, and the permissions involved are exactly the ones the web form needs. The script route is fast and wide, and it operates with your full session authority. The strong versus weak delete setting is the concrete expression of that difference, since one mode reaches everything the account can reach and the other stays inside what the account itself added.

There is also a middle option that decomoji itself points at, the Slack Custom Emoji Manager extension, which gives drag and drop registration without a script. For a team that wants maybe fifty of the basic set and does not want to run a Node tool, that extension is the more proportionate choice.

The third alternative is a different aesthetic entirely, picking an existing emoji set from a marketplace or building your own images in your brand style. decomoji's pitch, in the README's own terms, is a high context set built around abbreviations and character density, and it says as much: the images are deliberately packed with words, which is the whole point of the format and also the reason it will not blend with a minimalist emoji set.

Whichever route you take, the useful part of this repository is the artwork and the management tooling, and the artefacts you actually keep are the images in your workspace.

Editorial conclusion

decomoji fits a team that wants a large, consistent set of text-style custom emoji on Slack and is willing to run a bulk registration script once, with a workspace admin who can add and remove custom emoji. It does not fit a workspace that forbids uploading image assets or that has no admin rights, since registering custom emoji requires permission, and it does not fit anyone who wants a handful of reactions without granting a script that signs into their account. Before running it, read the list documentation for the category you intend to install, start with the 300 emoji basic set as the README advises, and run the script in a workspace you can undo, since the strong delete mode removes every matching emoji including ones other people added.

Frequently asked questions

Official sources

1. decomoji/decomoji on GitHub
2. Issues
3. License: MIT
4. README
5. Releases