This guide shows you how to use Gravatar avatars in your applications.
Gravatar (“Globally Recognized Avatar”) is a free service where users register profiles, incl. avatars, with their email addresses. When these users participate on any Gravatar-enabled site, the service can display their registered avatar based on their email address—no further authentication from the user needed.
How It Works
Gravatar uses a simple, straightforward mechanism based on email hashes to display avatars:
- User Signs Up: A user signs up for your service and provides their email address.
- Email Hashing: Your application creates a SHA256 hash of the user’s email address. This hash is used to construct a URL that links to their Gravatar.
- Avatar Display: You use this URL to display the user’s Gravatar wherever you need an avatar in your application.
Avatar Requests
Gravatar images may be requested just like a normal image, using an img tag. To get an image specific to a user, you must first calculate their email hash.
The most basic image request URL looks like this:
https://gravatar.com/avatar/HASH
where HASH is replaced with the calculated hash for the specific email address you are requesting. For example, here is my base URL:
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109
When wrapped in an img tag, that URL will produce:
<img src="https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109" />
If you require a file-type extension (some places do) then you may also add an (optional) .jpg extension to that URL:
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109.jpg
Code Examples
Size
By default, images are presented at 80px by 80px if no size parameter is supplied. You may request a specific image size, which will be dynamically delivered from Gravatar by using the s= or size= parameter and passing a single pixel dimension (since the images are square):
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109?s=200
You may request images anywhere from 1px up to 2048px, however note that many users have lower resolution images, so requesting larger sizes may result in pixelation/low-quality images.
Default Image
What happens when an email address has no matching Gravatar image? By default, this:
If you’d prefer to use your own default image you can easily do so by supplying the URL to an image in the d= or default= parameter. The URL should be URL-encoded to ensure that it carries across correctly, for example:
<img src="https://gravatar.com/avatar/000000000000000000000000000000000000000000000000000000?d=https%3A%2F%2Fexample.com%2Fimages%2Favatar.jpg" />
To URL-encode a string in PHP, you can use something like this:
echo urlencode( 'https://example.com/images/avatar.jpg' );
When you include a default image, Gravatar will automatically serve up that image if there is no image associated with the requested email hash. There are a few conditions which must be met for default image URL:
- MUST be publicly available (e.g. cannot be on an intranet, on a local development machine, behind HTTP Auth or some other firewall etc). Default images are passed through a security scan to avoid malicious content.
- MUST be accessible via HTTP or HTTPS on the standard ports, 80 and 443, respectively.
- MUST have a recognizable image extension (jpg, jpeg, gif, png, heic)
- MUST NOT include a querystring (if it does, it will be ignored)
In addition to allowing you to use your own image, Gravatar has a number of built in options which you can also use as defaults. Most of these work by taking the requested email hash and using it to generate a themed image that is unique to that email address. To use these options, just pass one of the following keywords as the d= parameter to an image request:
- initials: uses the profile name as initials, with a generated background and foreground color (beta). There are additional parameters, described later.
- color: a generated color (beta)
- 404: do not load any image if none is associated with the email hash, instead return an HTTP 404 (File Not Found) response
- mp: (mystery-person) a simple, cartoon-style silhouetted outline of a person (does not vary by email hash)
- 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
- robohash: a generated robot with different colors, faces, etc
- blank: a transparent PNG image (border added to HTML below for demonstration purposes)
Force Default
If for some reason you wanted to force the default image to always load, you can do that by using the f= or forcedefault= parameter, and setting its value to y.
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109?f=y
Rating
Gravatar allows users to self-rate their images so that they can indicate if an image is appropriate for a certain audience. By default, only ‘G’ rated images are displayed unless you indicate that you would like to see higher ratings. Using the r= or rating= parameters, you may specify one of the following ratings to request images up to and including that rating:
- 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 sexual imagery or extremely disturbing violence.
If the requested email hash does not have an image meeting the requested rating level, then the default image is returned (or the specified default, as per above) To allow images rated G or PG use something like this:
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109?r=pg
Initials
By default the initials avatar will show the initials attached to the avatar account. You can also supply your own initials through one of two parameters:
- initials – pass the initials to show
- name – pass the name and have the initials be extracted
Combining Parameters
You may combine any and all of the above parameters to produce more complex/refined requests. For example, this URL will request a 200px by 200px Gravatar rated G or PG, defaulting to a 404 response (no image) if there is not one associated with the requested email hash:
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109?s=200&r=pg&d=404
Secure Requests
As you may have noticed, all of the above example URLs start withhttps. You don’t need to do anything special to load Gravatars on a secure page, just make sure your Gravatar URLs start with https (or you can use the ‘protocol-agnostic’ approach of starting the URLs with ‘//’ which will automatically use https on a secure page, or http on an insecure one).
Gravatar Hovercards
Make your avatars even more useful: Gravatar Hovercards offer a dynamic way to display detailed user profiles associated with a Gravatar, simply by hovering over the Gravatar image. This feature is particularly useful for community sites, forums, and any web application where understanding user identity enhances the experience.
Key Benefits:
- Enhanced User Interaction: Provides quick access to user details without navigating away from the current page.
- Seamless Integration: Easily integrates with existing Gravatar images using a simple JavaScript snippet.
See the Hovercard implementation guide here.
Special Thanks
To Scott for identicons and monsterids To Shamus for wavatars
Gravatar For Developers