DiceBear Avatars

• Installation
• Quick Start
• Plugin Configuration
  • Style
  • Universal Options
  • Style-Specific Options
  • Seed Resolver
  • Caching
  • Self-Hosting
• Per-Model Customization
  • With Uploaded Photo Fallback
  • With Style-Specific Options
• Available Styles
  • Minimalist
  • Characters
• Configuration File
• Testing
• License

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

Register the plugin and avatar provider in your panel:

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

#Characters

#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.