WordPress.org

Ready to get started?Download WordPress

Codex

How to Use Gravatars in WordPress

Contents

What is a Gravatar?

When browsing different web sites, you may notice that many users have a picture next to their name. These pictures are called "avatars." WordPress, however, uses a specific type of avatar called "Gravatars"--short for "Globally Recognized Avatar." Unlike standard avatars, Gravatars follow you around the web and automatically appear when you post a comment on a WordPress site.

Example of a Gravatar on a Comment

WordPress integrates Gravatars into every WordPress site. Once registered with Gravatar, the service matches your WordPress profile information to the email address registered with Gravatar and displays your custom Gravatar image next to comments and (optionally) elsewhere on the WordPress site. If you choose not to sign up with Gravatar, the default icon set by the Administrator appears next to your name.

Why use Gravatars?

Providing your users with avatars has become a convention in web-publishing. Enabling Gravatars on your WordPress site simplifies the process for everyone involved. While it is possible to use a WordPress Plugin to manage user avatars on your WordPress-run site, using Gravatars on your site makes less work for both you and your site’s users.

Benefits for Administrators

  • You can add user Gravatars with very little effort
  • You don’t need to maintain an additional Plugin
  • You don’t have to manage user accounts, or their images, for commenters to use Gravatars on your site

Benefits for Users

  • You don’t need to register for every site you visit just to use a Gravatar
  • You can update the Gravatar you use across multiple sites by uploading a single image in a single place

Using Gravatars on your Site

To start using Gravatars on your site:

  1. Log in as an administrator to your site
  2. Navigate to Settings > Discussion and scroll down to the “Avatar” Section
  3. The “Avatar” section presents you with several options:
    • Avatar Display: Toggle Gravatars on and off for your site.
    • Maximum Rating: When users create a profile on Gravatar, they are given the opportunity to rate their Gravatar image as G, PG, R, X based on its appropriateness. Select the radio button for the maximum rating you would like displayed on your site.
    • Default Avatar: WordPress allows for you to select what image you would like to display when a commenter does not have a Gravatar account. Selecting one of the “generated” icons gives you and your users some of the benefits of a Gravatar without requiring them to have a Gravatar account. The icons that say “generated” next to them take the email of the commenter and link it to an auto-generated image. Now, every time that commenter posts to your site, they will have the same unique image next to their name.

For Developers

Starting with WordPress 2.7, when you retrieve the comments on a post or page using wp_list_comments, WordPress will automatically retrieve your users' Gravatars. If you would like to retrieve a user's Gravatar without retrieving comments, you can use get_avatar.

Customizing how Gravatars are displayed

Using wp_list_comments allows you to customize how WordPress outputs your comments in your theme. It also controls the size of the Gravatar attached to the comments. By default, Gravatars are displayed at 32px x 32px. To change the size of the Gravatar, you can use the ‘avatar_size’ argument with wp_list_comments.

For example, to return a 50px x 50px Gravatar, you would call wp_list_comments like this:

<?php wp_list_comments( array( 'avatar_size' => '50' ) ); ?>

get_avatar works slightly different. The first argument you pass it must be a user's ID, email address or the comment object. You can then specify the size of the returned Gravatar, the URL for the default image you want to display if a user does not have a Gravatar, and the alternate text for the Gravatar image.

This will return a 50px x 50px Gravatar:

<?php echo get_avatar( 'email@example.com', 50 ); ?>

Customizing Gravatars with CSS

Because you can retrieve Gravatars with or without comments, you need to be specific with your CSS classes when styling Gravatars. When WordPress returns Gravatars, it assigns them the .avatar class. However, you don’t want to only target the class .avatar because it is generated in different contexts. For example, when you hover over the Gravatar in the WordPress admin bar, the Gravatar that appears has the .avatar class. If you were to change the CSS for the .avatar class, you would alter the style of both the Gravatar in your theme's comments and admin bar.

As the Twenty Eleven theme demonstrates, you can simply use an additional class to target a specific instance of a Gravatar.

This will change the display of Gravatars only in the Twenty Eleven theme's comments:

.commentlist .avatar {
	/*Insert
	Your
	Styling
	Here */
}

Create a Custom Default Avatar

If you don’t want to use any of the default images for users not registered with Gravatar, you can easily add your own by adding a filter to the avatar_defaults hook.

After uploading the new image to your theme files, add this to your theme’s function.php file:

<?php
add_filter( 'avatar_defaults', 'new_default_avatar' );

function new_default_avatar ( $avatar_defaults ) {
		//Set the URL where the image file for your avatar is located
		$new_avatar_url = get_bloginfo( 'template_directory' ) . '/images/new_default_avatar.png';
		//Set the text that will appear to the right of your avatar in Settings>>Discussion
		$avatar_defaults[$new_avatar_url] = 'Your New Default Avatar';
		return $avatar_defaults;
}
?>

Now, go to Settings > Discussion and select your new avatar from the list.

Select Your New Default Avatar

From now on, all your users that don't use Gravatar will have this avatar next to their comments.

Custom Default Avatar in Use

Using Gravatar’s Hovercards

If you want to use Gravatar’s Hovercard feature, like on WordPress.com, you can install the Jetpack Plugin.

An example of a Hovercard

Resources