Twemoji

Twitter opensourced Twitter Emoji and the official JavaScript implementation is available at twemoji.

This RubyGem twemoji is a minimum implementation of Twitter Emoji in Ruby so that you can use emoji in your Ruby/Rails apps too!

Note: This gem might not implement all the features available in the JavaScript implementation.

Twemoji Gem and twemoji.js versions

• Twemoji Gem 3.x supports twemoji.js V2 (1661 emojis) Preview
• Twemoji Gem 2.x supports twemoji.js V1 (874 emojis) Preview

Preview pages' Images is CC-BY 4.0 by Twitter/Twemoji.

Installation

Add this line to your application's Gemfile:

gem "twemoji"

And then execute:

$ bundle

Or install it yourself as:

$ gem install twemoji

Integration

• Integration with HTML::Pipeline

Twemoji and Rails

• Checkout this tutorial: Twemoji in Rails

Rails Helper

$ touch app/helpers/emoji_helper.rb

module EmojiHelper
  def emojify(content, **options)
    Twemoji.parse(h(content), options).html_safe if content.present?
  end
end

In your ERb view:

<%= emojify "I like chocolate :heart_eyes:!" %>

will render

I like chocolate <img class="emoji" draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/72x72/1f60d.png">!

More options could be passed in, please see Twemoji.parse options for more details.

Usage

API

Twemoji.find_by text or code or unicode

> Twemoji.find_by(text: ":heart_eyes:")
=> "1f60d"

> Twemoji.find_by(code: "1f60d")
=> ":heart_eyes:"

> Twemoji.find_by(unicode: "😍")
=> ":heart_eyes:"

> Twemoji.find_by(unicode: "\u{1f60d}")
=> ":heart_eyes:"

Twemoji.find_by_text

> Twemoji.find_by_text(":heart_eyes:")
=> "1f60d"

Twemoji.find_by_code

> Twemoji.find_by_code("1f60d")
=> ":heart_eyes:"

Twemoji.find_by_unicode

> Twemoji.find_by(unicode: "😍")
=> ":heart_eyes:"

Twemoji.render_unicode

> Twemoji.render_unicode ":heart_eyes:"
=> "😍"

> Twemoji.render_unicode "1f60d"
=> "😍"

Twemoji.parse

> Twemoji.parse "I like chocolate :heart_eyes:!"
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/svg/1f60d.svg" class="emoji">!'

Twemoji.parse options

asset_root

Default assets root url. Defaults to https://twemoji.maxcdn.com/2/:

> Twemoji.parse "I like chocolate :heart_eyes:!", asset_root: "foocdn.com"
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="foocdn.com/svg/1f60d.svg" class="emoji">!'

file_ext

Default assets file extensions. Defaults to svg.

Can change to "png":

> Twemoji.parse 'I like chocolate :heart_eyes:!', file_ext: "png"
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/72x72/1f60d.png" class="emoji">!'

class_name

Default image CSS class name. Defaults to "emoji".

> Twemoji.parse "I like chocolate :heart_eyes:!", class_name: "superemoji"
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/svg/1f60d.svg" class="superemoji">!'

img_attrs

List of image attributes for the img tag. Optional.

> Twemoji.parse "I like chocolate :heart_eyes:!", class_name: "twemoji", img_attrs: { style: "height: 1.3em;" }
=> 'I like chocolate <img draggable="false" title=":heart_eyes:" alt="😍" src="https://twemoji.maxcdn.com/2/svg/1f60d.svg" class="twemoji" style="height: 1.3em;">!'

attribute value can apply proc-like object, remove : from title attribute:

> no_colons = ->(name) { name.gsub(":", "") }

> Twemoji.parse "I like chocolate :heart_eyes:!", class_name: "twemoji", img_attrs: { title: no_colons }
=> 'I like chocolate <img draggable="false" title="heart_eyes" alt="😍" src="https://twemoji.maxcdn.com/2/svg/1f60d.svg" class="twemoji">!'

Twemoji.emoji_pattern

> Twemoji.emoji_pattern
=> /(:mahjong:|:black_joker:| ... |:registered_sign:|:shibuya:)/

JSON for your front-end

We prepare two constants: Twemoji::PNG and Twemoji::SVG (not loaded by default), you need to require them to use:

require "twemoji/png" # If you want to use Twemoji::PNG
require "twemoji/svg" # If you want to use Twemoji::SVG

Or require at Gemfile:

# Require the one you need, require Twemoji::PNG
gem "twemoji", require: "twemoji/png"

# Or Twemoji::SVG
gem "twemoji", require: "twemoji/svg"

# Or both
gem "twemoji", require: ["twemoji/png", "twemoji/svg"]

Then you can do to_json to feed your front-end.

You can also make custom format by leverage Twemoji.codes:

# emojis.json.erb
<%= Twemoji.codes.collect do |code, _|
  Hash(
    value: code,
    html: content_tag(:span, Twemoji.parse(code).html_safe + " #{code}" )
  )
end.to_json.html_safe %>

Configuration

Twemoji.parse options can be given in configure block, default values are:

Twemoji.configure do |config|
  config.asset_root = "https://twemoji.maxcdn.com/2"
  config.file_ext   = "svg"
  config.class_name = "emoji"
  config.img_attrs  = {}
end

Specify additional img attributes like so:

config.img_attrs  = { style: "height: 1.3em;" }

Tips (from twitter/twemoji)

Inline Styles

If you'd like to size the emoji according to the surrounding text, you can add the following CSS to your stylesheet:

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

This will make sure emoji derive their width and height from the font-size of the text they're shown with. It also adds just a little bit of space before and after each emoji, and pulls them upwards a little bit for better optical alignment.

UTF-8 Character Set

To properly support emoji, the document character must be set to UTF-8. This can done by including the following meta tag in the document

<meta charset="utf-8">

Attribution Requirements

IMPORTANT: Please follow the Attribution Requirements as stated on the official Twemoji (JS) repo.

Contributing

Please see the CONTRIBUTING.md file.

Credits

A huge THANK YOU to all our contributors! ❤️

The emoji keywords are from jollygoodcode/emoji-keywords.

License

Please see the LICENSE.md file.

Maintained by Jolly Good Code

We specialise in rapid development of high quality MVPs. Hire us to turn your product idea into reality.