README

Deterministic avatar URLs for light and dark designs: Gravatar or Libravatar photos falling back to colored initials via ui-avatars.com. Same input, same URL, always.

Also available for Python and JavaScript.

Install

composer require stevelacey/ui-avatars

Usage

avatar_url(name: 'Ada Lovelace', email: 'ada@example.com');
// Gravatar photo, falling back to generated initials

avatar_url(name: 'Ada Lovelace');
// straight ui-avatars.com URL, no Gravatar lookup

avatar_url(name: 'Ada Lovelace', email: 'ada@example.com', image: $photoUrl);
// uploaded photo, falling back to Gravatar or initials

avatar_url(email: 'ada@example.com');
// initials from the first two letters of the email

avatar_url(name: 'Ada Lovelace', alpha: 0.75, size: 256, rounded: true);
// pass any of the options as one-off overrides

avatar_url(name: 'Ada Lovelace', mask: 'hexagon', format: 'webp');
// crop the image to a hexagon and serve webp via wsrv.nl

avatar_url(name: 'Ada Lovelace', email: 'ada@example.com', source: 'libravatar');
// look up the photo on Libravatar instead of Gravatar

avatar_url(email: 'ada@example.com', host: 'example.com', source: 'secure.gravatar.com');
// override hostnames to use custom/self-hosted servers

Arguments

At least one of name or email is required.

Name	Description
`name`	Name used to generate initials
`email`	Email address used to look up a photo via Gravatar or Libravatar
`image`	Image URL, e.g. an uploaded photo

Relative image URLs and images on local hosts, e.g. localhost, *.test or private IPs, can't be reached by the proxy, so they're served as they are, without cropping, masks, or a fallback.

Options

Options can be configured globally or overridden per call.

Name	Default	Description
`alpha`	`0.2`	Background opacity (`0` to `1`)
`background`		Pin the background color
`bold`	`true`	Bold the initials
`colors`	`Avatars::COLORS`	List of hex values or `[background, text]` pairs
`fontColor`		Pin the text color
`fontSize`	`0.4`	Size of the initials (`0.1` to `1`)
`format`		Image format, e.g. `png`, `svg`, and other formats
`hash`	`sha256`	Email hash for photo lookups, `sha256` or `md5`
`host`	`ui-avatars.com`	User initials avatars host
`length`	`2`	Number of initials
`mask`		Shape mask, e.g. `hexagon`, `pentagon`, `square`, and other masks
`proxy`	`wsrv.nl`	Proxy for masks, rounding, and extra formats
`region`		Service region, e.g. `eu` or `na` (ignored if `host` is set)
`rounded`	`false`	Round the image (ignored if `mask` is set)
`size`	`128`	Image size in pixels
`source`	`gravatar`	Photo source, e.g. `gravatar`, `libravatar`, or any compatible host
`uppercase`	`true`	Uppercase the initials

Configuration

Call Avatars::configure() statically to configure the shared instance that avatar_url() uses, or construct your own:

use SteveLacey\UiAvatars\Avatars;

Avatars::configure(colors: ['#1d4ed8', '#b91c1c'], size: 256, rounded: true);
avatar_url(name: 'Ada Lovelace', email: 'ada@example.com');
// or Avatars::build(name: 'Ada Lovelace', email: 'ada@example.com');

$avatars = new Avatars(colors: ['#1d4ed8', '#b91c1c'], size: 256, rounded: true);
$avatars->build(name: 'Ada Lovelace', email: 'ada@example.com');

Colors

The default color palette is Tailwind's 500 shades in rainbow order, Avatars::COLORS. Swap it for your own:

Avatars::configure(colors: ['#f00', '#0f0', '#00f']);

Pair colors manually with [background, text] pairs. Set alpha: 1 for solid backgrounds:

Avatars::configure(alpha: 1, colors: [['#f00', '#fff'], ['#000', '#00f']]);

To override the palette and force a specific color, pass the color argument:

avatar_url(name: 'Ada Lovelace', email: 'ada@example.com', color: '#f00');

To pin the background color, text color, or both, pass background and fontColor:

avatar_url(name: 'Ada Lovelace', alpha: 1, background: '#f00', fontColor: '#000');

Trait

use SteveLacey\UiAvatars\HasAvatarUrl;

class User
{
    use HasAvatarUrl;
}

$user->getAvatarUrl();
$user->getAvatarUrl(size: 64, rounded: true);

If you want to configure the instance, override getAvatarGenerator():

use SteveLacey\UiAvatars\Avatars;

public function getAvatarGenerator(): Avatars
{
    return new Avatars(size: 64, source: 'libravatar');
}

By default, the trait uses display_name, full_name, name, first_name and last_name, or username for initials, and avatar, profile_photo_path, profile_picture, or image for images, in that order.

Override getAvatarName(), getAvatarEmail(), or getAvatarImage() if needed:

class User
{
    use HasAvatarUrl;

    public function getAvatarImage(): ?string
    {
        return $this->photo_url;
    }
}

Laravel

The service provider is auto-discovered. It configures the shared instance from config/ui-avatars.php, so publish the config to change the defaults:

php artisan vendor:publish --provider="SteveLacey\UiAvatars\Laravel\ServiceProvider"

// config/ui-avatars.php
return [
    'colors' => ['#1d4ed8', '#b91c1c'],
    'rounded' => true,
    'size' => 256,
];

On Eloquent models, the trait reads attributes and accessors, and adds an avatar_url attribute:

use SteveLacey\UiAvatars\HasAvatarUrl;

class User extends Authenticatable
{
    use HasAvatarUrl;

    protected $appends = ['avatar_url'];
}

$user->avatar_url;

Image paths stored on the model, e.g. avatars/ada.png in an avatar column, are turned into URLs on the public disk. Change it with the disk config option.

If your images live elsewhere, e.g. Media Library, override getAvatarImage():

public function getAvatarImage(): ?string
{
    return $this->getFirstMediaUrl('avatar') ?: null;
}

Jetstream

Swap Jetstream's HasProfilePhoto trait for ours, so users without an uploaded photo get Gravatar and initials instead of Jetstream's default:

use SteveLacey\UiAvatars\Jetstream\HasProfilePhoto;

class User extends Authenticatable
{
    use HasProfilePhoto;
}

Filament

Filament shows avatar_url for users with the trait automatically. To use these avatars for every user and tenant, set the default avatar provider on your panel:

use SteveLacey\UiAvatars\Filament\AvatarProvider;

$panel->defaultAvatarProvider(AvatarProvider::class);

Development

composer install
composer test
composer lint

License

MIT

stevelacey / ui-avatars

Package info

Security

Statistics