README

A DiceBear v10 avatar provider for Filament panels. Supports all 61 avatar styles (19 of them animated), renders natively in PHP with no network calls, and adds caching, per-model customization, custom style definitions, and self-hosted API support.

Upgrading from 1.x? See UPGRADE.md.

Installation

composer require leek/filament-dicebear

This pulls in DiceBear's native PHP core (dicebear/core) and the official style definitions (dicebear/styles).

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)
                    ->animated(),
            ]);
    }
}

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 61 available styles:

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

You can also pass a string:

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

Animation

19 styles ship an opt-in animation (marked ✓ in Available Styles). It is CSS inside the SVG, so it plays in a plain <img> tag and respects prefers-reduced-motion.

use Leek\FilamentDiceBear\Enums\AnimationSpeed;

DiceBearPlugin::make()
    ->style(DiceBearStyle::Planets)
    ->animated()                            // Random speed per seed
    ->animationSpeed(AnimationSpeed::Slow)  // Or pin it: Slowest, Slow, Medium, Fast, Fastest, None

Styles without an animation are unaffected, so it's safe to enable globally. DiceBearStyle::Thumbs->isAnimated() and DiceBearStyle::animated() tell you which styles animate.

Core Options

These map 1:1 to DiceBear's core options. Options that take a range accept a fixed value or a [min, max] pair that the seed samples from.

DiceBearPlugin::make()
    ->size(128)                  // Pixel dimensions (1–4096)
    ->borderRadius(50)           // Percent of canvas (0–50; 50 = circle)
    ->scale(0.9)                 // Scale factor (0–10; 1 = original)
    ->rotate([-10, 10])          // Degrees (−360–360)
    ->translateX(5)              // Percent of canvas width
    ->translateY(-5)             // Percent of canvas height
    ->flip('horizontal')         // 'none', 'horizontal', 'vertical', 'both' (or true)
    ->tags(['!mood:negative'])   // Variant tag filter

Background

DiceBearPlugin::make()
    ->backgroundColor(['b6e3f4', 'c0aede', 'd1d4f9'])  // Hex, '#' optional
    ->backgroundColorFill('linear')                    // 'solid', 'linear', 'radial'
    ->backgroundColorFillStops(3)                      // Gradient stops (min 2)
    ->backgroundColorAngle([0, 90])                    // Gradient angle
    ->backgroundColorOrder('fixed')                    // Use colors in the given order

Accessibility & Typography

These options work with the local driver and self-hosted APIs. The public HTTP API ignores them.

DiceBearPlugin::make()
    ->title('User avatar')           // Adds role="img" and a <title>
    ->fontFamily(['Inter', 'sans-serif'])  // Text-based styles, e.g. initials
    ->fontWeight(600)
    ->idRandomization()              // Unique SVG ids when inlining several avatars

Any other core option can be set by name with ->setCoreOption('name', $value).

Style-Specific Options

Each style exposes per-component and per-color options. Pass them with options():

DiceBearPlugin::make()
    ->style(DiceBearStyle::BotttsNeutral)
    ->options([
        'eyesVariant' => ['bulging', 'eva', 'happy', 'hearts'],
        'mouthVariant' => ['diagram', 'smile01', 'smile02'],
        'mouthProbability' => 80,
    ])

• {component}Variant: restrict variants. Pass ['short01' => 2, 'long01' => 1] to weight them (weights are local driver only).
• {component}Probability: chance (0–100) that the component appears.
• {color}Color, {color}ColorFill, {color}ColorFillStops, {color}ColorAngle, {color}ColorOrder: override a palette, e.g. 'skinColor' => ['f2d3b1'].

Each style page lists its options, or fetch https://api.dicebear.com/10.x/<style>/options.json.

Custom Styles

Render your own style from a DiceBear definition JSON file (hand-written or exported with the Figma plugin):

DiceBearPlugin::make()
    ->customStyle('brand', resource_path('avatars/brand.json'))

Or register them in config under custom_styles and select them with ->style('brand'). Custom styles are always rendered locally as SVG.

Seed Resolver

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

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

Rendering Driver

By default, avatars are rendered in-process by DiceBear's native PHP core. There are no network calls or rate limits, every option is supported, and the output is byte-identical to the HTTP API.

To use the HTTP API instead, for example a self-hosted instance:

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

Raster formats are rendered by the HTTP API automatically:

DiceBearPlugin::make()
    ->format('webp')  // 'svg' (default), 'png', 'jpg', 'webp', 'avif'

If rendering fails, the provider falls back to the HTTP API URL. Local failures are passed to report(), so invalid options show up in your logs.

Caching

Rendered avatars are cached to disk by default:

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

Cache filenames hash the options together with the DiceBear core and styles versions (or the API version), so upgrading DiceBear never serves stale avatars. When caching is disabled, the avatar is returned as a base64 data URI.

To clear cached avatars:

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

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 [
            'eyesVariant' => ['bulging', 'eva', 'frame1', 'frame2', 'happy', 'hearts'],
            'mouthVariant' => ['diagram', 'smile01', 'smile02'],
            'tags' => ['animation'],
        ];
    }
}

Available Styles

Styles are licensed by their creators. See DiceBear's license overview.

Minimalist

Characters

Scenes

Configuration File

// config/filament-dicebear.php
return [
    'driver' => 'local',          // 'local' or 'http'
    'format' => 'svg',            // 'svg', 'png', 'jpg', 'webp', 'avif'
    'style' => 'initials',
    'custom_styles' => [
        // 'brand' => resource_path('avatars/brand.json'),
    ],
    'animation' => [
        'enabled' => false,
        'speed' => null,          // 'none', 'slowest', 'slow', 'medium', 'fast', 'fastest'
    ],
    'options' => [
        // Any core option by its v10 name, e.g. 'size' => 128, 'borderRadius' => 50
    ],
    'api_version' => '10.x',
    'base_url' => 'https://api.dicebear.com',
    'cache' => [
        'enabled' => true,
        'disk' => 'public',
        'path' => 'avatars/dicebear',
    ],
];

Testing

composer test

More Filament plugins by Leek

Premium

• Filament UI Plus — Enhanced UI components: dual sub-navigation, animated sidebar, horizontal-scroll tables, loading bar, and more.
• Filament Workflow Engine — Automated workflows with a visual builder, triggers/actions, async execution, and audit logging.
• Filament Decision Tables — Business rules engine with spreadsheet-style decision tables.

Free & open source

• Filament Right Click — Right-click context menus for table rows.
• Filament Header Filters — Inline filters attached to table column headers.
• Filament Subtenant Scope — Second-level tenancy scoping via a topnav dropdown.

License

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