README

A DiceBear avatar provider for Filament panels. Supports all 31 avatar styles with caching, per-model customization, and self-hosted instances.

Installation

composer require leek/filament-dicebear

Optionally publish the config file:

php artisan vendor:publish --tag=filament-dicebear-config

Quick Start

use Leek\FilamentDiceBear\DiceBearPlugin;
use Leek\FilamentDiceBear\DiceBearProvider;
use Leek\FilamentDiceBear\Enums\DiceBearStyle;

class AppPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->defaultAvatarProvider(DiceBearProvider::class)
            ->plugins([
                DiceBearPlugin::make()
                    ->style(DiceBearStyle::Thumbs),
            ]);
    }
}

That's it! All users without a custom avatar will now display a DiceBear avatar.

Plugin Configuration

All configuration methods are optional and return the plugin instance for fluent chaining.

Style

Choose from any of the 31 available styles:

DiceBearPlugin::make()
    ->style(DiceBearStyle::Adventurer)

You can also pass a string:

DiceBearPlugin::make()
    ->style('bottts-neutral')

Universal Options

These correspond to DiceBear's universal query parameters:

DiceBearPlugin::make()
    ->size(128)              // Pixel dimensions
    ->radius(50)             // Corner radius (0-50)
    ->scale(80)              // Scale (0-200)
    ->rotate(45)             // Rotation (0-360)
    ->flip()                 // Mirror horizontally
    ->backgroundColor('ff0000')       // Hex color(s), comma-separated
    ->backgroundType('gradientLinear') // 'solid' or 'gradientLinear'

Style-Specific Options

Pass any style-specific parameters via options():

DiceBearPlugin::make()
    ->style(DiceBearStyle::BotttsNeutral)
    ->options([
        'eyes' => 'bulging,eva,happy,hearts',
        'mouth' => 'diagram,smile01,smile02',
    ])

See the DiceBear docs for available options per style.

Seed Resolver

By default, the provider uses the model's id as the seed. Customize it:

DiceBearPlugin::make()
    ->seedUsing(fn ($record) => $record->email)

Caching

SVGs are cached to disk by default to avoid repeated API calls:

DiceBearPlugin::make()
    ->cache(true)                    // Enable/disable (default: true)
    ->disk('public')                 // Storage disk (default: 'public')
    ->cachePath('avatars/dicebear')  // Cache directory (default: 'avatars/dicebear')

When caching is disabled, the SVG is returned as a base64 data URI.

To clear cached avatars:

Storage::disk('public')->deleteDirectory('avatars/dicebear');

Self-Hosting

For production use or commercial projects, you may want to self-host DiceBear:

DiceBearPlugin::make()
    ->baseUrl('https://dicebear.example.com')
    ->apiVersion('9.x')

Per-Model Customization

Use the HasDiceBearAvatar trait on any model implementing HasAvatar to customize avatars per model:

use Filament\Models\Contracts\HasAvatar;
use Leek\FilamentDiceBear\Concerns\HasDiceBearAvatar;
use Leek\FilamentDiceBear\Enums\DiceBearStyle;

class User extends Model implements HasAvatar
{
    use HasDiceBearAvatar;

    public function dicebearAvatarStyle(): DiceBearStyle
    {
        return DiceBearStyle::Thumbs;
    }
}

With Uploaded Photo Fallback

Override getCustomAvatarUrl() to check for uploaded photos first:

class User extends Model implements HasAvatar
{
    use HasDiceBearAvatar;

    protected function getCustomAvatarUrl(): ?string
    {
        if ($this->avatar_url) {
            return Storage::url($this->avatar_url);
        }

        return null; // Falls back to DiceBear
    }

    public function dicebearAvatarStyle(): DiceBearStyle
    {
        return DiceBearStyle::Thumbs;
    }
}

With Style-Specific Options

class ClientProfile extends Model implements HasAvatar
{
    use HasDiceBearAvatar;

    public function dicebearAvatarStyle(): DiceBearStyle
    {
        return DiceBearStyle::BotttsNeutral;
    }

    public function dicebearAvatarOptions(): array
    {
        return [
            'eyes' => 'bulging,eva,frame1,frame2,happy,hearts',
            'mouth' => 'diagram,smile01,smile02',
        ];
    }
}

Available Styles

Minimalist

Style	Slug	License
Glass	`glass`	CC0 1.0
Icons	`icons`	MIT
Identicon	`identicon`	CC0 1.0
Initials	`initials`	CC0 1.0
Rings	`rings`	CC0 1.0
Shapes	`shapes`	CC0 1.0
Thumbs	`thumbs`	CC0 1.0

Characters

Style	Slug	Creator	License
Adventurer	`adventurer`	Lisa Wischofsky	CC BY 4.0
Adventurer Neutral	`adventurer-neutral`	Lisa Wischofsky	CC BY 4.0
Avataaars	`avataaars`	Pablo Stanley	Free
Avataaars Neutral	`avataaars-neutral`	Pablo Stanley	Free
Big Ears	`big-ears`	The Visual Team	CC BY 4.0
Big Ears Neutral	`big-ears-neutral`	The Visual Team	CC BY 4.0
Big Smile	`big-smile`	Ashley Seo	CC BY 4.0
Bottts	`bottts`	Pablo Stanley	Free
Bottts Neutral	`bottts-neutral`	Pablo Stanley	Free
Croodles	`croodles`	vijay verma	CC BY 4.0
Croodles Neutral	`croodles-neutral`	vijay verma	CC BY 4.0
Dylan	`dylan`	Natalia Spivak	CC BY 4.0
Fun Emoji	`fun-emoji`	Davis Uche	CC BY 4.0
Lorelei	`lorelei`	Lisa Wischofsky	CC0 1.0
Lorelei Neutral	`lorelei-neutral`	Lisa Wischofsky	CC0 1.0
Micah	`micah`	Micah Lanier	CC BY 4.0
Miniavs	`miniavs`	Webpixels	CC BY 4.0
Notionists	`notionists`	Zoish	CC0 1.0
Notionists Neutral	`notionists-neutral`	Zoish	CC0 1.0
Open Peeps	`open-peeps`	Pablo Stanley	CC0 1.0
Personas	`personas`	Draftbit	CC BY 4.0
Pixel Art	`pixel-art`	DiceBear	CC0 1.0
Pixel Art Neutral	`pixel-art-neutral`	DiceBear	CC0 1.0
Toon Head	`toon-head`	Johan Melin	CC BY 4.0

Configuration File

// config/filament-dicebear.php
return [
    'style' => 'initials',
    'api_version' => '9.x',
    'base_url' => 'https://api.dicebear.com',
    'size' => null,
    'radius' => null,
    'scale' => null,
    'rotate' => null,
    'flip' => null,
    'background_color' => null,
    'background_type' => null,
    'cache' => [
        'enabled' => true,
        'disk' => 'public',
        'path' => 'avatars/dicebear',
    ],
];

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.

leek / filament-dicebear

Maintainers

Details