tempi-marathon/filament-local-avatars

Local initials avatars via data-URI SVG

v1.2.0 2026-07-03 13:39 UTC

Requires

• php: ^8.3
• filament/filament: ^4.0|^5.0
• spatie/laravel-package-tools: ^1.93

Requires (Dev)

• larastan/larastan: ^3.1
• laravel/pint: ^1.29
• orchestra/testbench: ^11.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-laravel: ^4.0

MIT

• tempi-marathon

• laravel
• avatar
• filament
• filament-plugin
• filamentphp
• tempi-marathon
• filament-local-avatars

Published on Packagist.org on 2026-07-03 13:40 UTC

README

Local initials avatars for Filament panels, generated as inline SVG data URIs. No third-party services, no HTTP routes, GDPR-friendly.

Requirements

• PHP 8.3+
• Filament 4.x or 5.x

Installation

composer require tempi-marathon/filament-local-avatars

Register the plugin on your panel:

use TempiMarathon\FilamentLocalAvatars\FilamentLocalAvatarsPlugin;

return $panel
    // ...
    ->plugin(FilamentLocalAvatarsPlugin::make());

The plugin sets the panel's default avatar provider automatically.

Configuration

Publish the config file (optional):

php artisan vendor:publish --tag=filament-local-avatars-config

Available options in config/filament-local-avatars.php:

Key	Default	Description
size	120	SVG width and height in pixels
font_size	48	Initials font size
text_color	#FFFFFF	Initials color
background_color	null	Default background color when a record has no per-record color; null uses the panel primary color

Per-record background colors

Implement HasAvatarBackgroundColor on any model that should have its own avatar background color. Add a column (for example avatar_color) in your app and return it from the interface method:

use TempiMarathon\FilamentLocalAvatars\Contracts\HasAvatarBackgroundColor;

class User extends Authenticatable implements HasAvatarBackgroundColor
{
    public function getAvatarBackgroundColor(): ?string
    {
        return $this->avatar_color;
    }
}

Background color resolution order:

1. Record color from getAvatarBackgroundColor() when non-empty
2. background_color config value when set
3. Panel primary color

Text color remains global via the text_color config option.

Local development

When developing the package alongside a consumer app, add a Composer path repository:

"repositories": [
    {
        "type": "path",
        "url": "../filament-local-avatars",
        "options": { "symlink": true }
    }
]

composer require tempi-marathon/filament-local-avatars:@dev

Testing

composer test

Runs Pint, PHPStan (max level), and Pest with a minimum 90% code coverage requirement.

License

MIT. See LICENSE.