Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Dependency Status devDependency Status Coverage Status bitHound Overall Score npm version npm downloads

Avatar is a JavaScript library for showing Gravatars or generating user avatars.


There are several examples on the website.

import Avatar from 'avatar-initials';
const avatar = new Avatar(document.getElementById('avatar'), {
  'useGravatar': false,
  'initials': 'MC',

This example will render an avatar with my initials "MC" as the image.

Avatar Example


Avatar is highly customizable and most options are self explanatory:

  useGravatar: true, // Allow Gravatars or not.
  fallbackImage: '', // URL or Data URI used when no initials are provided and not using Gravatars.
  size: 80,          // Size in pixels, fallback for hidden images and Gravatar

  // Initial Avatars Specific
  initials: '',          // Initials to be used.
  initial_fg: '#888888', // Text Color
  initial_bg: '#f4f6f7', // Background Color
  initial_size: null,    // Text Size in pixels
  initial_weight: 100,   // Font weight (numeric value for light, bold, etc.)
  initial_font_family: "'Lato', 'Lato-Regular', 'Helvetica Neue'",

  // Gravatar Specific
  hash: null,                   // Precalculated MD5 string of an email address
  email: null,                  // Email used for the Gravatar
  fallback: 'mm',               // Fallback Type
  rating: 'x',                  // Gravatar Rating
  forcedefault: false,          // Force Gravatar Defaults
  allowGravatarFallback: false, // Use Gravatars fallback, not fallbackImage

  // GitHub Specific
  github_id: null,  // GitHub User ID.

  // Specific
  use_avatars_io: false, // Enable Support
  avatars_io: {
    user_id: null,       // User ID
    identifier: null,    // Avatar Identifier
    twitter: null,       // Twitter ID or Username
    facebook: null,      // Facebook ID or Username
    instagram: null,     // Instagram ID or Username
    size: 'medium',      // Size: small, medium, large

  setSourceCallback: null, // Callback called when image source is set (useful to cache avatar sources provided by third parties such as Gravatar)


npm install --save avatar-initials


<script src="md5.js"></script>
<script src="avatar.js"></script>

Avatar expects a window.md5() function to be defined in order to generate the hashes needed for Gravatars.

jQuery Support

I haven't used jQuery in a long time and don't need it personally, so if you still use it the old helper is below.

if (typeof jQuery !== 'undefined') {
  jQuery.fn.avatar = function avatar(options) {
    return this.each(() => {
      /* istanbul ignore else */
      if (!, 'plugin_avatar')) {, 'plugin_avatar', new Avatar(this, options));

Running Tests

To execute all unit tests, open test/index.html in your target browser.


If you used any version less than 3 and still need to use it, you can stick to v2.6.0 or use the new build/avatar.browser.js build. If you are using Parcel or Webpack or similar the npm version should work fine.

Browser Support

I build with the Babel Env Preset and target "browsers": ["last 2 versions", "ie 11"]. If you need to support older browsers, you will need to use older versions or polyfill yourself. The ES201X versions are exposed on module and jsnext:main. Below are the browsers I have tested on personally:


  • OS X 10.10.2 - Chrome 41.0.2243.2 dev (64-bit)
  • OS X 10.10.2 - Firefox 34.0
  • OS X 10.10.2 - Safari 8.0.3 (10600.3.10.2)
  • iOS 8.1.2 - Safari 8
  • iOS 8.1.2 - Chrome 39
  • Microsoft Remote Desktop - Internet Explorer 11 (11.0.9879.0)


  • OS X 10.10.2 - Chrome 48.0.2541.0 dev (64-bit)
  • OS X 10.10.2 - Firefox 41.0.2
  • OS X 10.10.2 - Safari 9.0 (11601.1.56)


Pretty styles and design support kindly provided by Andrew Crocker. Originally built with love at Apptentive. Sun Knudsen for providing a PR with setSourceCallback.


  • npm - npm-bump major/minor/patch


Avatar is MIT licensed.

You can’t perform that action at this time.