Guide · Open source

How to use Twemoji: load the library and replace emoji with images

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Twemoji is a JavaScript library and image set from Twitter that replaces standard Unicode emoji characters with picture files, so emoji look the same across browsers and operating systems. This guide is for web developers and designers who want consistent emoji on a site. By the end you will know how to load the library, parse emoji in a page, size them with CSS and meet the attribution request.

Twemojitwitter/twemoji · ★ 17.8k · MIT Install options & downloads

Quick start

1Add the script. Place the unpkg script tag in the head of your HTML document.
2Set UTF-8. Add the meta charset utf-8 tag so emoji display correctly.
3Check your image host. Confirm where image files load from, since the default MaxCDN host is shut down.
4Call parse on an element. Pass document.body or another HTMLElement to twemoji.parse to replace emoji in text nodes.
5Set the sizing CSS. Add the img.emoji rule so images scale with surrounding text.
6Add attribution. Credit the CC-BY 4.0 graphics in a README, About section, footer or source comment.

Load Twemoji on your page

Add the library to the head of your HTML document. The README's first option loads the latest version from unpkg, which guarantees you always get the newest release of the library.

If you want a fixed version instead, the README shows a tag for the explicit release 14.0.3 with an integrity hash. The README also says that to download a specific version you should look at the gh-pages branch, which holds built assets for latest and older versions.

Use the unpkg tag for always-latest behaviour.
Use a pinned version tag with integrity if you want reproducible loading.
Or download the built assets from the gh-pages branch.

<script src="https://unpkg.com/twemoji@latest/dist/twemoji.min.js" crossorigin="anonymous"></script>

Check the CDN before you rely on the default images

The default image URLs point to a MaxCDN host. The README marks MaxCDN support as shut down and says to use a different CDN or download the assets yourself. Plan for this before launch, because the default image host may not load.

Parsing still works with the library, but you need a working image base. You can set the base option to your own host.

Parse emoji in the DOM (recommended)

The README recommends DOM parsing. When the first argument to twemoji.parse is an HTMLElement, it replaces emoji found inside text nodes with image tags. It does this without touching surrounding nodes or listeners and without using innerHTML.

The README notes this is the safest option, with a slight performance penalty from DOM operations. The generated img tags get the class emoji by default, have an alt attribute with the original character, and have draggable set to false.

twemoji.parse(document.body);

Customise the image source with options

The optional object passed to parse accepts callback, attributes, base, ext, className, size and folder. The defaults are base (the MaxCDN URL), ext ".png", className "emoji" and size "72x72". Changing twemoji.base, twemoji.ext or twemoji.size changes the defaults for all parsed content.

To use SVG images, pass a folder of svg and ext of .svg. The README says this produces URLs like the svg folder path instead of a size-based image.

base: where image files are loaded from.
ext: image file extension, default .png.
className: CSS class for each image, default emoji.
size: asset size, default 72x72.
folder: picks a folder such as svg; it replaces size when set.

twemoji.parse(genericNode, {
  folder: 'svg',
  ext: '.svg'
});

Size emoji to match your text

Add CSS to make emoji scale with the font size of the text around them. The README's rule sets height and width to 1em, adds a small margin on each side and nudges the image up slightly for alignment.

Also make sure the page is declared as UTF-8, since the README says that is required to support emoji properly.

Declare the character set with the meta tag charset utf-8 in the head.

img.emoji {
   height: 1em;
   width: 1em;
   margin: 0 .05em 0 .1em;
   vertical-align: -0.1em;
}

Exclude specific characters and add attribution

To stop certain characters from being replaced, call parse with a callback that returns false for those icon code points. The README example skips the copyright, registered trademark and trademark symbols.

The graphics are CC-BY 4.0. The README asks for attribution and says a mention in a project README, an About section, a website footer or the HTML/JS source is sufficient.

What people use it for

Showing user-generated comments with the same emoji look for every reader.
Adding emoji images to a page that needs consistent rendering across browsers.
Pulling SVG emoji into a design by using the folder option with svg files.
Excluding trademark symbols from replacement on a legal or brand page.

Frequently asked questions

Is Twemoji free to use?

The README says the graphics are licensed under CC-BY 4.0, and the project asks for attribution. The library is listed under the MIT licence. The README asks for a mention in a README, About section, footer or HTML/JS source.

How do I install Twemoji?

The README's main method is to add a script tag from unpkg in the head of your HTML: the latest version at dist/twemoji.min.js. You can also pin a specific version or download built assets from the gh-pages branch.

Why are my Twemoji images not loading?

The README says the MaxCDN host is shut down, so default image URLs may fail. Use a different CDN or download the assets, and set the base option to where you host them.

Can I use Twemoji with custom emoji?

No. The README states that custom emoji are not supported. Twemoji covers Unicode emoji recommended for general interchange, following Unicode 14.0 and Emoji 14.0 specs.

Is twemoji.parse safe for untrusted HTML?

Not for string input. The README says the string parser does not sanitize input or prevent malicious code. It recommends DOM parsing, which replaces emoji in text nodes without using innerHTML, though it is slightly slower.

How does Twemoji compare to Noto Emoji or OpenMoji?

Twemoji is a JavaScript library plus an image set, which the README describes as a library for standard Unicode emoji. Noto Emoji and OpenMoji are other emoji image sets listed as comparable projects here. Choose based on the look and licence you need.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Twemoji suits web developers and designers who want the same emoji images on every browser and OS, with a free CC-BY 4.0 image set. Skip it if you need custom emoji, want to pass untrusted HTML strings to the string parser, or cannot host images since the default MaxCDN host is shut down.

Install options & downloads