Steve Grunwell

Open-source contributor, speaker, and electronics tinkerer

Making Apps Personal with Gravatar

If you haven’t already implemented it in one of your own apps, you’ve almost certainly used a site that uses Gravatar, an Automattic-maintained project that provides the web with Globally-recognized avatars. WordPress sites naturally use them for author and commenter avatars, but Gravatars are also used by major sites like Stack Overflow, GitHub, and more.

For maximum portability, Gravatars are always square and can be automatically resized to fit most applications. Defaults can be specified, including several types of uniquely-generated avatars including identicons, wavatars, and the 8-bit inspired “retro” avatars. Let’s take a look at how easy it can be to implement Gravatar in your next project, shall we?

Creating a Gravatar

Gravatars are created and maintained through, which uses a (free) account for authentication. Once you’ve signed up, you’re encouraged to add your email addresses (you’ll need to be able to access each of them to verify ownership) and one or more photo to use as an avatar. These avatars can be assigned to any number of your email addresses, as you can see in the (shortened) list of addresses in my personal Gravatar account:

"Manage Gravatars" screen from the Gravatar website.

That Fahlgren Mortine address hasn’t been active for two years, so don’t bother, spammers.

We had company headshots taken when I worked at Fahlgren Mortine, so I chose to use my official headshot anytime I was using my company email address. For the rest of the web I use the “black shirt on a green background” photo, though I was still using the Mad Men Yourself illustration on a few addresses until recently.

Using Gravatars

Within WordPress, displaying a user’s Gravatar is as simple as calling get_avatar() in your theme, passing the user’s ID or email address.

If your site or app isn’t using WordPress, you’re still in luck as the “API” behind Gravatar is incredibly simple:

First you’ll need to generate the Gravatar’s hash from the user’s email address, which is simply an md5 hash of the address. For maximum consistency, the address should have leading/trailing whitespace stripped and be converted to lowercase. In PHP, this is a simple one-liner:

Next, we append this hash to the Gravatar endpoint:

That’s all we need to generate an 80px square representation of the user with email address “[email protected]”. Pretty simple, right?


Now, let’s say we want a larger version of the image, as 80px is pretty small. Simply append a query string with ?s=500, where 500px will be the width and height (remember, Gravatars are square) of the image:

Need the image to explicitly be a JPEG or PNG image? Simply append the extension to the hash:

Default avatars

Default GravatarNot everyone is going to have a Gravatar (though they totally should), so it’s important to note that Gravatar will automatically return a default image. If you don’t specify, the Gravatar logo will be returned. The default (?d=) parameter lets you specify what should be returned when no Gravatar is found. Options are:

  • A URL-encoded image URL. For example:
  • 404: returns a HTTP 404 response code.
  • mm: A simple, generic silhouette of a person.
  • identicon: a geometric pattern based on an email hash.
  • monsterid: a generated ‘monster’ with different colors, faces, etc.
  • wavatar: generated faces with differing features and backgrounds.
  • retro: awesome generated, 8-bit arcade-style pixelated faces.
  • blank: a transparent PNG image.


A feature I haven’t seen used much in practice but is important to be aware of is Gravatar ratings. Let’s say, for instance, an adult film star wants to use a rather explicit photo for his or her Gravatar. Upon upload, the user can specify a rating for the image, while sites requesting the Gravatar for display can specify a ?rating argument in the query string, limiting the maximum rating that can be displayed on the site.

The ratings recognized by Gravatar are:

  • g: suitable for display on all websites with any audience type.
  • pg: may contain rude gestures, provocatively dressed individuals, the lesser swear words, or mild violence.
  • r: may contain such things as harsh profanity, intense violence, nudity, or hard drug use.
  • x: may contain hardcore sexual imagery or extremely disturbing violence.

By default, Gravatar will only return G-rated images, so a family-friendly food blog won’t display the star’s hardcore Gravatar, while the adult film industry blog that user frequents could choose to add ?rating=x to its Gravatar strings to permit any rating of imagery.

Delivery over SSL

If your site is running over SSL, loading Gravatars from will cause insecure content warnings for your visitors. Fortunately, Gravatars can also be served from or, better yet, served using a protocol-relative URL (e.g. <img src="//" />).

Performance implications

If your site or application plans to make extensive use of Gravtar, it’s worth weighing the performance implications. After all, if you have a page listing 100 users with their Gravatars, that’s an addition 100 HTTP requests being made on page load. Gravatars are served via CDNs and are cached, but 100 extra requests can still weigh down your page load. Consider looking into lazy-loading strategies so the images are only actually loaded when necessary.

Bonus: Profiles

A lesser-used feature within the Gravatar service is the Global Profile, which can be accessed in a manner very similar to Gravatars. These profiles can be great for sites that are building communities around their users without wanting to introduce full profile editing capabilities. Another common implementation is to display user bios when a visitor mouses over the Gravatar, ala Hovercards.

Wrapping up

The Gravatar service is incredibly easy to get started with; from personal experience, the hardest part is encouraging users to sign up for the free account. We’ve covered many common uses here, but what are other cool things you’ve seen done with Gravatars and/or profiles?


Quick Tip: JavaScript Resize Timer


Bypassing JavaScript Anti-Clipboard Measures


  1. As far as performance considerations, it’s likely it will be more performant to serve up Gravatars than it would be to serve locally.

    Not only do you get the benefits of the CDN, which is a separate domain, allowing additional browser requests (see, but anyone who has previously viewed a page with Gravatars will have them cached in the browser.

    • Agreed. I’m not advocating for serving locally, just maybe not loading the actual Gravatars until they’re necessary.

  2. Piping in late, but… I’m trying to figure out how exactly to use Gravatar Hovercards on a non-WP application. There seems to be a lot of ‘magic’ going around, but, so far, I found two applications that are able to implement them: Open Source Classifieds (, which seems to be able to fully implement Hovercards with minimal JS (basically the same that is loaded by the WP Jetpack plugin); and Octopress, which constructs a ‘static hovercard profile’ (so, not a popup) as part of the profile itself, basically writing the whole HTML for the hovercard from scratch and embedding it on the Octopress profile without using Automattic’s JS for the Hovercard, but simply filling the needed fields by extracting the from the Gravatar profile site.

    I’m looking for better examples, but there still seems to be an aura of mystery around Gravatar Hovercards. Automattic probably doesn’t want them to appear outside WP.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Be excellent to each other.