Skip to content
A handy little npm package to handle, get, or convert emoji short codes, unicodes, or image tags.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.eslintrc.json chore(eslint): updates eslint config to specify jest May 16, 2017


NPM version NPM downloads Build Status Dependency Status Codecov Codacy Badge semantic-release npm

A handy little library (written as a Node.js module) for converting emoji short codes into HTML image tags. This is mostly a project to force myself to go through all the steps of creating a Node module.


Calvin and Hobbes




$ npm install -g emoji-transmogrifier


Using the module is currently available from the command line as a brief utility to autmoate the conversion of the short code strings in markdown or html files and for traditional Node module consumption (aka- via a require() statement).

CLI Utility

The command line tool now has the previous functionality under the zap command and provides the server module's getImage and getUnicode functionality exposed by the unicode (or uni) and url (or href) commands, respectively. The zap command keeps the same -d (or --directory) and -t (or --type) as before, but will default to the current directory and markdown files ending in .md.

For specifics about a give command, invoke the command followed by -h, such as emoji-transmogrifier zap -h.

  Usage: emoji-transmogrifier <cmd>


    zap   			convert emoji short codes in specified files (globbing pattern, defaults to `**/*.md`) to image tags
    unicode|uni     returns the unicode interpretation of the given emoji short code
    url|href        returns the GitHub url of the given emoji by short code


    -h, --help  output usage information

Server Module

var transmogrifier = require('emoji-transmogrifier');

var beerEmojiUrl = transmogrifier.getImage('beer');
console.log('the url of the GitHub emoji image for beer is: '+beerEmojiUrl);

var beerUniStr = transmogrifier.getUnicode('beer');
console.log('the unicode string for beer is: '+beerUniStr);


This project was born from the need I had to convert the emoji short codes, a la :smile:, to an HTML image tag, for use with a book I'm writing with gitbook. The web static version generated by gitbook was fine with some scripts I had injected to handle them, but ran into issues when generating the pdf, mobi, or epub versions of the book, yielding the original short code text. This project is the next evolutionary version of the script I created to perform the conversion.

RegEx Pattern

At the heard of this task is a regular expression that performs the matching of the short code which is to be replaced.

The RegEx pattern I settled on can be viewed and tested against the known emoji short codes by viewing the pattern here:

The pattern itself:


Road Map

  • complete coveralls implementation
  • add alternate cli function of exposing the internal methods to the 'server' module
    • provide return of image path (href)
    • provide return of unicode string
  • provide current conversion function ability to traverse subdirectories
  • add range support, as discussed in #20


Please consult and follow the contribution guide prior to submitting any Pull Requests.



You can’t perform that action at this time.