react-emoji-component
react-emoji-component
is the most lightweight (~17kB gzipped) and most versatile
library for using the open EmojiOne v4.0
emoji set with React. You can count on this library to be up-to-date with the
latest EmojiOne version.With this library you can easily use your own CDN provider to host emoji sprites and PNG files and customize emoji rendering. You can also switch between using sprites and singular PNG icons for the lightest possible experience. This is something I've yet to see in other React EmojiOne libraries.
Demo
Check out the demo on RunKitExamples
Check out this example on your local machine and be mesmerized as every emoji known to man or woman loads effortlessly on a single page.Installation
react-emoji-component on Yarn • react-emoji-component on NPM
yarn add react-emoji-component
or npm i react-emoji-component
Basic Usage
import Emojis from 'react-emoji-component'
<Emojis size={24}>
You 👏🏻 should 👏🏻 be 👏🏻 using 👏🏻 <code>react-emoji-component</code>
</Emojis>
// ['You', <img key=..>, 'should', <img key=..>, 'be', <img key=..>, 'using', <img key=..>, <code>react-emoji-component</code>]
import {toEmojis} from 'react-emoji-component'
toEmojis('You 👏🏻 should 👏🏻 be 👏🏻 using 👏🏻 react-emoji-component', {size: 24})
// ['You', <img key=..>, 'should', <img key=..>, 'be', <img key=..>, 'using', <img key=..>, 'react-emoji-component']
Exports
<Emojis>
(default
export)
EmojiOne icons
- This is the default emoji renderer provided silently by default to the`<Emojis render={}/>` prop. It renders `<img>` elements and the emoji
character as alt-text to maintain copy-ability when highlighting text.
- This is an alternative emoji renderer for the <Emojis render={}/>
prop.This component uses `<span role='img'>` elements with sprites in the
`background-image` property.
- This function creates a new <Emojis>
component based upon provided options.This is highly useful for configuring CDN paths and EmojiOne sprite-usage
without having to declare those props each time you use the base `Emojis`
component.
- Parses a string and returns an array of React components withthe proper emoji mappings
- Creates an img src
string from Emoji data
- Creates a style
object from Emoji data
- Creates a -
delimited list of the codePoints found in the emoji withoutempty joiners
- Returns true
if the environment supports image/webm
format
- The grapheme splitter used to split strings into constituent partsDocumentation
<Emojis>
Props
- children
anything React can render
React elements, etc. The only children that are transformed by this component
are string emojis.
- render
function
Emoji
- This prop provides a functional component which is rendered each time an emojiis encountered in your child string. See [`Emoji`](#emoji) for prop types.
- size
number
16
- This is the width and height you want your emoji to render to. With the freelicense for EmojiOne, the max size you can render is `128px` without blur.
- hiDpi
bool
false
- By setting hiDpi
to true
, you will create more crisp emojis for high DPIdevices with the tradeoff that the image transfer size will be larger.
- publicPath
string
- Images: `https://cdn.jsdelivr.net/emojione/assets/4.0/png/`
- Sprites: `https://github.com/jaredLunde/react-emoji-component/blob/master/assets/sprites/`
- This is the public path to your EmojiOne sprites and image files. It allowsyou to self-host those files instead of using the defaults.
- extension
string
png
- This is the file extension used for your EmojiOne sprites and image files.Its inclusion allows you to self-host those files and transform them to
something like JPEG-XR or WebP instead of PNG.
<Emoji>
This emoji renderer will create an <img>
element linked to the proper EmojiOne
emoji image. It is automatically provided to <Emojis>
by default as its render
prop.Props
- emoji
string
- codePoint
string
and PNGs
- options
object
number
- See [Emojis](#emojis)
- hiDpi bool
- See [Emojis](#emojis)
- publicPath string
- See [Emojis](#emojis)
- extension string
- See [Emojis](#emojis)
<EmojiSprite>
This emoji renderer will use a <span>
and background-image
along with a
CSS sprite instead of an <img>
element. Its options are the same as
Emoji.import {Emojis, EmojiSprite} from 'react-emoji-component'
<Emojis render={EmojiSprite} size={48}>
Seriously! You 👏🏻 should 👏🏻 be 👏🏻 using 👏🏻 <code>react-emoji-component</code>
</Emojis>
See createEmojisComponent below for an example of how to create your own
<Emojis>
component with the EmojiSprite
as the default renderer.createEmojisComponent(options)
You can use this to create your own default <Emojis>
component. See
Emojis for options.
import {createEmojisComponent, EmojiSprite} from 'react-emoji-component'
const MyEmojis = createEmojisComponent({
size: 24,
publicPath: '/path/to/emoji/sprites',
render: EmojiSprite
})
toEmojis(string, options)
Returns an Array
of React elements with string emojis replaced by Emoji
React
components
import {toEmojis} from 'react-emoji-component'
toEmojis('You 👏🏻 should 👏🏻 be 👏🏻 using 👏🏻 react-emoji-component', {size: 24})
// ['You', <img key=..>, 'should', <img key=..>, 'be', <img key=..>, 'using', <img key=..>, 'react-emoji-component']
toImage(codePoint, options)
Returns an img src
string for the file associated with the codePoint/emojitoSprite(codePoint, options)
Returns a style
object for the sprite associated with the codePoint/emojiemojiToCodePoints(emoji)
Creates a -
delimited list of the codePoints found in the emoji without
empty joiners.
emojiToCodePoints('👨🏾🚒')
// "1f468-1f3fe-1f692"
supportsWebP()
Returns true
if the current environment supports the image/webm
formatsplit(string)
Splits a string by its graphemes and returns an Array
of constituent characters.react-emoji-component/assets
copy(destinationPath, options)
This is a utility for copying EmojiOne assets such as sprites and PNGs to
a local destination in your project. It is useful for self-hosting your
emoji set.
import {copy} from 'react-emoji-component/assets'
copy('/path/to/your/public/files', {excludeSprites: true})
Options
- excludePNG
bool
false
- Excludes the single-icon image assets from the copy call- excludeSprites
bool
false
- Excludes the sprite image and css assets from the copy call- excludeJSON
bool
false
- Excludes the emoji.json
file from the copy call.copy-emoji-assets [destinationPath] [--excludePNG] [--excludeJSON] [--excludeSprites]
This package comes with a binary for easily copying the EmojiOne assets to a
local destination.See 2ality for more information about local node bins.
node_modules/.bin/copy-emoji-assets public/images/emojione --excludeSprites
WebP example
This contrived example assumes you've already usedreact-emoji-component/assets
to copy files to your local destination and that you've already transcoded
the files to the image/webm
format. I'm merely giving hints here about how to
use the createEmojisComponent()
function to your ultimate advantage.import {createEmojisComponent, EmojiSprite, supportsWebP} from 'react-emoji-component'
// use the built-in supportsWebP() function to determine if the browser
// supports it
const useWebP = supportsWebP()
// <img>
const Emojis = createEmojisComponent({
publicPath: useWebP ? '/path/to/webp' : '/path/to/png',
extension: useWebP ? '.webp' : '.png'
})
<Emojis size={24}>
We 👏 have 👏 got 👏 WebP 👏 files
</Emojis>
// <span> sprites
const Emojis = createEmojisComponent({
publicPath: useWebP ? '/path/to/webp/sprites' : '/path/to/png/sprites',
extension: useWebP ? '.webp' : 'png',
render: EmojiSprite,
})
<Emojis size={24}>
We 👏 have 👏 got 👏 WebP 👏 files
</Emojis>
Attributions
- Emoji icons provided free by EmojiOne
- Graphemes split by orling/grapheme-splitter