Using WordPress ‘get_avatar’ PHP filter

The get_avatar WordPress PHP filter allows you to modify the HTML output for a user’s avatar.

Usage

add_filter('get_avatar', 'your_custom_function', 10, 6);
function your_custom_function($avatar, $id_or_email, $size, $default_value, $alt, $args) {
    // your custom code here
    return $avatar;
}

Parameters

  • $avatar (string): HTML for the user’s avatar.
  • $id_or_email (mixed): The avatar to retrieve. Accepts a user_id, Gravatar MD5 hash, user email, WP_User object, WP_Post object, or WP_Comment object.
  • $size (int): Square avatar width and height in pixels to retrieve.
  • $default_value (string): URL for the default image or a default type. Accepts ‘404’, ‘retro’, ‘monsterid’, ‘wavatar’, ‘indenticon’, ‘mystery’, ‘mm’, ‘mysteryman’, ‘blank’, or ‘gravatar_default’.
  • $alt (string): Alternative text to use in the avatar image tag.
  • $args (array): Arguments passed to get_avatar_data(), after processing.

More information

See WordPress Developer Resources: get_avatar

Examples

Add a custom CSS class to the avatar

This example adds a custom CSS class ‘my-custom-class’ to the avatar image.

add_filter('get_avatar', 'add_custom_class_to_avatar', 10, 6);
function add_custom_class_to_avatar($avatar, $id_or_email, $size, $default_value, $alt, $args) {
    $custom_class = 'my-custom-class';
    $avatar = str_replace('class="', 'class="' . $custom_class . ' ', $avatar);
    return $avatar;
}

Replace the default avatar

This example replaces the default avatar with a custom image URL.

add_filter('get_avatar', 'replace_default_avatar', 10, 6);
function replace_default_avatar($avatar, $id_or_email, $size, $default_value, $alt, $args) {
    $custom_avatar_url = 'https://example.com/your-custom-avatar.png';
    $avatar = preg_replace("/src='(.*?)'/i", "src='$custom_avatar_url'", $avatar);
    return $avatar;
}

Add a custom attribute to the avatar

This example adds a custom ‘data-custom’ attribute to the avatar image.

add_filter('get_avatar', 'add_custom_attribute_to_avatar', 10, 6);
function add_custom_attribute_to_avatar($avatar, $id_or_email, $size, $default_value, $alt, $args) {
    $custom_attribute = 'data-custom="example"';
    $avatar = str_replace('<img ', '<img ' . $custom_attribute . ' ', $avatar);
    return $avatar;
}

Change avatar size based on user role

This example changes the avatar size based on the user’s role.

add_filter('get_avatar', 'change_avatar_size_based_on_role', 10, 6);
function change_avatar_size_based_on_role($avatar, $id_or_email, $size, $default_value, $alt, $args) {
    $user = false;

    if (is_numeric($id_or_email)) {
        $user = get_user_by('id', (int) $id_or_email);
    }} elseif (is_object($id_or_email)) {
if (!empty($id_or_email->user_id)) {
$user = get_user_by('id', (int) $id_or_email->user_id);
}
} else {
$user = get_user_by('email', $id_or_email);
}

if ($user && in_array('administrator', (array) $user->roles)) {
    $size = 100; // Set the size for administrator role
} else {
    $size = 50; // Set the size for other roles
}

$args['size'] = $size;
$avatar = get_avatar($user, $size, $default_value, $alt, $args);

return $avatar;
}

Add a custom image overlay to the avatar

This example adds a custom image overlay on top of the user’s avatar.

add_filter('get_avatar', 'add_custom_overlay_to_avatar', 10, 6);
function add_custom_overlay_to_avatar($avatar, $id_or_email, $size, $default_value, $alt, $args) {
    $overlay_url = 'https://example.com/your-custom-overlay.png';
    $avatar = preg_replace_callback(
        '/<img(.*?)>/i',
        function ($matches) use ($overlay_url) {
            return '<div style="position: relative; display: inline-block;">' . $matches[0] . '<img src="' . $overlay_url . '" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" alt="Overlay">' . '</div>';
        },
        $avatar
    );
    return $avatar;
}