gemoji Ruby Library

To use this library, add gemoji to your Gemfile.

gem 'gemoji'

You can implement a helper to convert text containing emoji aliases (e.g., :cat:) into HTML <img> tags. This example uses Emoji.find_by_alias to locate the emoji and generates an image tag using the emoji's image_filename.

module EmojiHelper
  def emojify(content)
    h(content).to_str.gsub(/:([\w+-]+):/) do |match|
      if emoji = Emoji.find_by_alias($1)
        %(<img alt="#$1" src="#{image_path("emoji/#{emoji.image_filename}")}" style="vertical-align:middle" width="20" height="20" />)
      else
        match
      end
    end.html_safe if content.present?
  end
end

You can programmatically add new emoji characters to the Emoji.all list using Emoji.create.

When creating new emojis, you must ensure that you also provide the image files referenced by their image_filename in your assets directory.

If you create a custom emoji without Unicode aliases, emoji.custom? will return true and the image_filename will default to the emoji's name with a .png extension.

# Adding a new emoji with aliases and tags
emoji = Emoji.create("music") do |char|
  char.add_alias "song"
  char.add_unicode_alias "\u{266b}"
  char.add_tag "notes"
end

# Creating a custom emoji (no Unicode aliases)
emoji = Emoji.create("music") do |char|
  char.add_tag "notes"
end

# Customizing the image filename
emoji = Emoji.create("music") do |char|
  char.image_filename = "subdirectory/my_emoji.gif"
end

Use the Emoji class to map between emoji aliases and their Unicode characters.

• Use Emoji.find_by_alias(name).raw to get the Unicode character from an alias.
• Use Emoji.find_by_unicode(unicode_string).name to get the alias from a Unicode character.

>> Emoji.find_by_alias("cat").raw
=> "🐱"

>> Emoji.find_by_unicode("\u{1f431}").name
=> "cat"

To modify an existing emoji (such as adding new aliases or tags), find the emoji first and then use Emoji.edit_emoji within an edit block.

emoji = Emoji.find_by_alias "musical_note"

Emoji.edit_emoji(emoji) do |char|
  char.add_alias "music"
  char.add_unicode_alias "\u{266b}"
  char.add_tag "notes"
end

For emojis that support the Fitzpatrick scale, you can manage and retrieve skin tone variants:

• skin_tones?(): Returns true if the emoji supports skin tone modifiers.
• attr_writer :skin_tones: Allows setting whether the emoji supports skin tones.
• raw_skin_tone_variants: Returns an array of raw Unicode strings for each skin tone variant. For emojis depicting multiple people (like couples), it applies modifiers to both persons in specific cases (e.g., PEOPLE_HOLDING_HANDS).

You can access various metadata properties for an Emoji::Character instance:

• raw(): Returns the raw Unicode string for the emoji. Returns nil if the emoji is non-standard (custom).
• custom?(): Returns true if the emoji is not a standard Unicode emoji.
• unicode_aliases: A list of Unicode strings that uniquely refer to this emoji.
• add_unicode_alias(str): Adds a Unicode string to the unicode_aliases list.
• category: The emoji's category (per Apple's character palette).
• description: The Unicode description text.
• unicode_version: The Unicode spec version where the emoji debuted.
• ios_version: The iOS version where the emoji debuted.