Gem for creating letter avatar from user's name (or any other strong / character).

Code extracted from discourse source (thanks guys!) - I needed this functionality in three projects, so here's the gem! :-)

Gem Version Code Climate


Google's Inbox Palette


System requirements

$ sudo apt-get install -y imagemagick

Mac OS X

$ brew install imagemagick ghostscript

Add this line to your application's Gemfile:

gem 'letter_avatar'

And then execute:

$ bundle

Or install it yourself as:

$ gem install letter_avatar


LetterAvatar.setup do |config|
  config.fill_color        = 'rgba(255, 255, 255, 1)' # default is 'rgba(255, 255, 255, 0.65)'
  config.cache_base_path   = 'public/system/lets'     # default is 'public/system'
  config.colors_palette    = :iwanthue                # default is :google
  config.weight            = 500                      # default is 300
  config.annotate_position = '-0+10'                  # default is -0+5
  config.letters_count     = 2                        # default is 1
  config.pointsize         = 70                       # default is 140

Color palette

We have three color palettes implemented: iwanthue, google and custom.

Each of them have different colors, but the iwanthue also differently calculates the color for specified username.

The google selected will generate the same avatar for both, "Krzysiek" and "ksz2k" usernames given (both of them starts with letter "k"), but iwanthue will calculate it's md5 and then selects color, so there's huge chance that these usernames get different colors.

Custom palette definition

You can define your own custom palette:

LetterAvatar.setup do |config|
  config.colors_palette = :custom
  config.custom_palette = [[120, 132, 205], [91, 149, 249], [72, 194, 249], [69, 208, 226]]
Custom font definition

You can define your own custom palette:

LetterAvatar.setup do |config|
  config.font = File.join(File.expand_path('../../', File.dirname(__FILE__)), 'app/assets/fonts', 'font_name.ext')


LetterAvatar.generate 'ksz2k', 200
=> "public/system/letter_avatars/2/K/87_178_230/200.png"

In your controllers / views

There's also helper for this. To use it, you need:

  • in your helper (eg. ApplicationHelper) or controller:
  include LetterAvatar::AvatarHelper
  • and in your view:
  letter_avatar_for('ksz2k', 200)
  => "public/system/letter_avatars/2/K/87_178_230/200.png"
  # or
  letter_avatar_url('ksz2k', 200)
  => "/system/letter_avatars/2/K/87_178_230/200.png"
  # or even
  letter_avatar_tag('ksz2k', 200, class: 'av')
  => "<img class=\"av\" alt=\"ksz2k\" src=\"/system/letter_avatars/2/K/87_178_230/200.png\" />"

In your model

Say, you have a model User (which must have attribute or method name)

require 'letter_avatar/has_avatar'

class User
  include LetterAvatar::HasAvatar

  def name

Then, in your views you can use:

=> "public/system/letter_avatars/2/K/87_178_230/200.png"
# or
=> "/system/letter_avatars/2/K/87_178_230/200.png"

Way to support non [a-z0-9] charsets

class User
  def username_for_avatar
    # Translate Chinese hanzi to pinyin
    # https://github.com/flyerhzm/chinese_pinyin

Then you can get right avatar now:

letter_avatar_for(user.username_for_avatar, 200)
# or
letter_avatar_tag(user.username_for_avatar, 200, class: 'av')


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request