Twemoji

repository·master·Indexed 12 days ago

A library that provides standard Unicode emoji support across all platforms by replacing emoji characters with consistent image assets. Version 14.0.3 includes features for DOM and string parsing via twemoji.parse(), configuration options for asset rendering, and utility methods for converting between HEX codepoints and UTF-16 surrogate pairs.

Tokens: 2.3K
Snippets: 13
Records: 13
Agent score: 47%

What's inside Twemoji

Install Twemoji via CDN

master

To use Twemoji in your web project, include the library in your HTML <head> tag. You can use unpkg to always get the latest version, or specify a version explicitly for stability.

Latest version:

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

Explicit version (v14.0.3):

<script src="https://unpkg.com/twemoji@14.0.3/dist/twemoji.min.js" integrity="sha384-eoGiwFCoIsUzdZGbvJ/7h/ICofqh5LolgoDnsgdbLptvnpK4+/swGDdkv3sb6bq+" crossorigin="anonymous"></script>

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

Install Twemoji Legacy API (V1) via CDN
master
To use the V1 version of the Twemoji library via CDN, include the following script tag in the <head> of your HTML document. Using this specific URL guarantees you are using the legacy V1 version.
```
<script src="https://twemoji.maxcdn.com/1/twemoji.min.js" crossorigin="anonymous"></script>
```
https://github.com/twitter/twemoji/blob/master/LEGACY.md
Style Twemoji for inline text alignment
master
To make emojis scale with surrounding text and align correctly, add the following CSS to your stylesheet. This ensures the emoji inherits the font-size and maintains proper optical alignment.
```
img.emoji {
   height: 1em;
   width: 1em;
   margin: 0 .05em 0 .1em;
   vertical-align: -0.1em;
}
```
```
img.emoji {
   height: 1em;
   width: 1em;
   margin: 0 .05em 0 .1em;
   vertical-align: -0.1em;
}
```
https://github.com/twitter/twemoji/blob/master/README.md
Ensure UTF-8 support for emojis
master
To properly support emoji rendering, your document must use the UTF-8 character set. Include this meta tag in the <head> of your HTML:
```
<meta charset="utf-8">
```
```
<meta charset="utf-8">
```
https://github.com/twitter/twemoji/blob/master/README.md
Style Twemoji images with CSS
master
To ensure emoji scale correctly with surrounding text and align visually, add the following CSS to your stylesheet:
```
img.emoji {
   height: 1em;
   width: 1em;
   margin: 0 .05em 0 .1em;
   vertical-align: -0.1em;
}
```
```
img.emoji {
   height: 1em;
   width: 1em;
   margin: 0 .05em 0 .1em;
   vertical-align: -0.1em;
}
```
https://github.com/twitter/twemoji/blob/master/LEGACY.md

Exclude specific characters from Twemoji parsing

master

To prevent certain Unicode characters from being replaced by Twemoji images, use the callback option in twemoji.parse() and return false for the specific icons you wish to exclude.

twemoji.parse(document.body, {
    callback: function(icon, options, variant) {
        switch ( icon )
            case 'a9':      // © copyright
            case 'ae':      // ® registered trademark
            case '2122':    // ™ trademark
                return false;
        return ''.concat(options.base, options.size, '/', icon, options.ext);
    }
});

Exclude specific characters from parsing

master

To prevent certain Unicode characters from being replaced by Twemoji, use the callback option in twemoji.parse(). If the callback returns false, the character will not be replaced.

twemoji.parse(document.body, {
    callback: function(icon, options, variant) {
        switch ( icon ) {
            case 'a9':      // © copyright
            case 'ae':      // ® registered trademark
            case '2122':    // ™ trademark
                return false;
        }
        return ''.concat(options.base, options.size, '/', icon, options.ext);
    }
});

twemoji.parse(document.body, {
    callback: function(icon, options, variant) {
        switch ( icon ) {
            case 'a9':      // © copyright
            case 'ae':      // ® registered trademark
            case '2122':    // ™ trademark
                return false;
        }
        return ''.concat(options.base, options.size, '/', icon, options.ext);
    }
});

Parse strings with twemoji.parse()
master
The twemoji.parse() method can take a string as its first argument. It replaces all emoji characters within that string with <img> tags.
Security Warning: String parsing does not sanitize the input. If the string contains <script> tags, they will not be escaped. For security-sensitive applications, use DOM parsing instead.
```
twemoji.parse('I \u2764\uFE0F emoji!');

// produces: I <img class="emoji" draggable="false" alt="❤️" src="https://twemoji.maxcdn.com/36x36/2764.png"/> emoji!
```
https://github.com/twitter/twemoji/blob/master/LEGACY.md
Convert between Code Points and UTF-16 Surrogates
master
Twemoji provides utility methods to handle emoji encoding conversions.
twemoji.convert.fromCodePoint(hex) Converts a HEX codepoint to a UTF-16 surrogate pair.
```
twemoji.convert.fromCodePoint('1f1e8');
// returns "\ud83c\udde8"
```
twemoji.convert.toCodePoint(surrogates, [separator]) Converts UTF-16 surrogate pairs back to a HEX codepoint string. You can optionally provide a separator (default is -).
```
twemoji.convert.toCodePoint('\ud83c\udde8\ud83c\uddf3');
// returns "1f1e8-1f1f3"

twemoji.convert.toCodePoint('\ud83c\udde8\ud83c\uddf3', '~');
// returns "1f1e8~1f1f3"
```
```
twemoji.convert.fromCodePoint('1f1e8');
twemoji.convert.toCodePoint('\ud83c\udde8\ud83c\uddf3');
```
https://github.com/twitter/twemoji/blob/master/README.md
Parse DOM elements with twemoji.parse()
master
To safely parse emoji within an existing DOM structure, pass an HTMLElement as the first argument to twemoji.parse().
Unlike string parsing, DOM parsing only replaces emoji inside #text nodes. This avoids using innerHTML, preserving surrounding nodes and event listeners, making it the safer option for security-conscious applications.
```
var div = document.createElement('div');
div.textContent = 'I \u2764\uFE0F emoji!';
document.body.appendChild(div);

twemoji.parse(document.body);
```
https://github.com/twitter/twemoji/blob/master/LEGACY.md
Use twemoji.convert utilities
master
The twemoji.convert namespace provides helpers for handling emoji code points and UTF-16 surrogate pairs.
- twemoji.convert.fromCodePoint(hex): Converts a HEX codepoint to a UTF-16 surrogate pair string.
- twemoji.convert.toCodePoint(surrogates, [separator]): Converts UTF-16 surrogate pairs back to a HEX codepoint string. Use a separator (like ~) if passing multiple code points.
```
twemoji.convert.fromCodePoint('1f1e8');
// "\ud83c\udde8"

twemoji.convert.toCodePoint('\ud83c\udde8\ud83c\uddf3');
// "1f1e8-1f1f3"

twemoji.convert.toCodePoint('\ud83c\udde8\ud83c\uddf3', '~');
// "1f1e8~1f1f3"
```
https://github.com/twitter/twemoji/blob/master/LEGACY.md

Use twemoji.parse() for DOM parsing

master

The recommended way to use Twemoji is via DOM parsing. When you pass an HTMLElement to twemoji.parse(), the library replaces emoji inside #text nodes with <img> tags. This method is safe because it avoids innerHTML and does not compromise surrounding nodes or event listeners.

var div = document.createElement('div');
div.textContent = 'I \u2764\uFE0F emoji!';
document.body.appendChild(div);

twemoji.parse(document.body);

var img = div.querySelector('img');
// img.src will be the Twemoji asset URL
// img.className will be 'emoji'

var div = document.createElement('div');
div.textContent = 'I \u2764\uFE0F emoji!';
document.body.appendChild(div);

twemoji.parse(document.body);