@entva/emojify
v1.1.0
Published
Converts emojis to images
Downloads
7
Maintainers
Readme
Emojify 😘
In a given string convert unicode and :shortcode:
emojis to <img />
tags using asset packages like https://joypixels.com.
Unicode version
Currently supported Unicode version: 15.0
. Minimum supported emoji-assets
version: 8.0.0
.
Usage:
This package is a collection of utility functions loosely based on twemoji
and joypixels
legacy javascript libraries. It
aims to completely replace those with a modern ES implementation, full unicode spec support and flexible image
collection support. SVG sprites are not supported for performance reasons. For best results pair
with https://github.com/joypixels/emoji-assets.
Functions:
isSingleEmoji(string)
Determines if string contains only a single emoji. Automatically trims whitespace before checking. Returns bool.
shortnamesToUnicode(string)
Takes a string with shortnames and returns a string with every known emoji shortname replaced with corresponding unicode representation. Ignores unknown shortnames.
unicodeToShortnames(string)
Opposite of shortnamesToUnicode
.
renderShortnameToString(string, options)
Takes a string with shortnames and returns a string with every known emoji shortname replaced with an image tag. Useful
for rendering specific emojis when it's easier to use :bacon:
instead of 🥓. For a list of supported options check
below.
renderToString(string, options)
Takes a string with unicode emojis and returns a string with every known emoji sequence replaced with an image tag. Useful for rendering user generated content. For a list of supported options check below.
renderToArray(string, callback)
Takes a string with unicode emojis and returns an array of mixed data. Calls callback for every known emoji sequence
to be replaced with any kind of data you like (React Fragments, Vue specific data structure etc).
The callback will be called with 3 arguments: image name, unicode symbol and replacement index. Useful for
using native rendering within your target UI framework. Returned array will be filtered out to omit empty
strings. Return null
or an empty string from the callback function to strip away emojis.
emojiCollection
An array of objects containing all supported emojis. Format is:
{
category: "people", // emoji category according to spec
hex: "1f603", // hex representation used to reference images
shortname: ":smiley:", // shortname representation, legacy so no aliases are supported
suggest: true // should this emoji appear in suggestions based on current support by major OS versions
}
emojiRegex
String containing regular expression for a single emoji character supported by this library and assets. Usage:
const myRegex = new RegExp(emojiRegex); // do stuff
shortnameRegex
Same as emojiRegex
, but for shortnames.
Options:
Render functions and some helper functions support these options. This list contains keys and their default values.
{
size: 64, // size of emojis to use when the default CDN is used, supported sizes are: 32, 64, 128
className: null, // CSS class to use when rendering image tags
unsafe: false, // when set to true, render will NOT sanitize the string, e.g. it forces "unsafe" output
single: false, // when the string contains just a single emoji this speeds up render a bit
cdn: undefined, // CDN to use for image paths
}
By default, the path to emoji images is constructed like this: /images/emojis-v${version}/${size}
. version
is
the https://github.com/joypixels/emoji-assets version used to generate the emojis.json file and size
is the asset
size (32/64/128).
Example output: /images/emojis-v8.0.0/64/1f603.png
. When cdn
option is specified, it will be used
instead. When just a size
is specified, default path will be used with size
being replaced by the one provided in
options.
TypeScript
Every function described in this readme is fully typed, you shoudn't need any additional type declarations.
Maintenance
There is a number of internal scripts available to re-generate and update this package from time to time.
You can run these scripts via node run <script>
generate
This will download the current unicode spec file unless cached locally, generate an emoji collection, compare that collection against assets package and generate new vendor/emojis.json dictionary as well as new regex for matching. Based on excellent work of Mathias Bynens: emoji-regex. His package is not used here because we need to only include emojis currently supported by the assets package, not every emoji in the spec.
extract
Extracts current emoji-assets description json and puts it in .tmp/
folder.
suggestable
Shows every emoji with suggest: true. Use inline
flag to have output in one line instead of a list:
node run suggestable inline
spec_test
Tries to render every emoji in current unicode spec and checks for potential errors.
device_test
Tries to render every emoji located in scaffolding/emojis_ios.txt or
scaffolding/emojis_android.txt
and checks for potential errors. By default uses ios
spec, pass android
flag to check android emojis:
node run device_test android
License
This project is published under MIT license. See LICENSE file for more details.