Filament Svg Avatar Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require voltra/filament-svg-avatar
   

2. Publish the config (optional, for global settings):

   php artisan vendor:publish --tag="filament-svg-avatar-config"
   

3. Register as a plugin in your PanelProvider:

   use Voltra\FilamentSvgAvatar\FilamentSvgAvatarPlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               FilamentSvgAvatarPlugin::make()
                   ->backgroundColor(Hex::fromString('#3b5998'))
                   ->textColor(Hex::fromString('#e9ebee')),
           ]);
   }
   

First Use Case

Replace default Gravatar/URL-based avatars with inline SVG avatars (no external HTTP requests). Ideal for:

• Performance: Eliminate avatar image loading delays.
• Customization: Style avatars with custom colors/fonts.
• Offline-first: Work without internet (e.g., PWA or local dev).

Implementation Patterns

1. Plugin Integration (Recommended)

Use the plugin for global SVG avatar replacement with minimal setup:

FilamentSvgAvatarPlugin::make()
    ->backgroundColor('#2563eb') // Hex or Spatie\Color\Hex
    ->textColor('#ffffff')
    ->svgSize(600) // Optional: Override global config
    ->disallowPluginOverride(true); // Prevent further overrides

Pros:

• Zero template overrides.
• Configurable via plugin methods or config/filament-svg-avatar.php.

2. Manual Avatar Provider Override

For fine-grained control, replace the default provider:

->defaultAvatarProvider(
    \Voltra\FilamentSvgAvatar\Filament\AvatarProviders\RawSvgAvatarProvider::class
)

Use case: When you need to extend the SvgAvatarService logic (e.g., dynamic initials logic).

3. Template Override (Advanced)

Replace Filament’s <x-filament::avatar/> with an SVG version:

php artisan vendor:publish --tag=filament-svg-avatar-core-overrides

Key files:

• resources/views/vendor/filament/components/avatar.blade.php
• resources/views/vendor/filament-svg-avatar/avatar-override.blade.php

When to use:

• Custom SVG attributes (e.g., viewBox, aria-label).
• Integration with custom Filament components.

4. Dynamic Configuration

Override defaults per-panel or per-resource:

// In a service provider:
$this->app->scoped(
    \Voltra\FilamentSvgAvatar\Contracts\SvgAvatarServiceContract::class,
    MyCustomSvgAvatarService::class
);

Example: Dynamic colors based on user roles:

class MyCustomSvgAvatarService extends FilamentSvgAvatarService
{
    public function getBackgroundColor(string $initials): string
    {
        return $initials === 'ADMIN' ? '#ef4444' : parent::getBackgroundColor($initials);
    }
}

Gotchas and Tips

Pitfalls

1. Font Availability:

   • SVGs render text as base64 if the font isn’t available on the user’s machine.
   • Fix: Use RawSvgAvatarProvider + publish the override template to ensure custom fonts work.

2. Plugin vs. Provider Order:

   • Register external providers after the plugin:

     ->plugins([FilamentSvgAvatarPlugin::make()])
     ->defaultAvatarProvider(MyCustomProvider::class) // Must come last!
     

3. Config Precedence:

   • Plugin methods > config/filament-svg-avatar.php > Service overrides.
   • Set disallowPluginOverride(true) to lock global settings.

4. Alt Attribute Bleeding:

   • Older versions added alt to SVGs (invalid). v1.2.5+ fixes this automatically.

Debugging Tips

• Check SVG output: Inspect the rendered HTML to verify SVG structure:

  <svg ...> <!-- Should NOT have `src` or `alt` -->
    <text x="50%" y="50%" dy=".3em">JD</text>
  </svg>
  

• Test font rendering: Use Chrome DevTools to check if custom fonts load in the SVG.

Extension Points

1. Custom Initials Logic: Override getInitials() in your SvgAvatarService to use:

   public function getInitials(string $name): string
   {
       return Str::of($name)->take(2)->upper()->value();
   }
   

2. Dynamic Sizes: Use the svgSize config or override the getSize() method in your service.
3. Theming: Extend the avatar-override.blade.php to add:

   <svg ... style="filter: drop-shadow(0 0 2px rgba(0,0,0,0.3))">
   

Performance Notes

• No HTTP requests: SVGs are generated server-side and embedded inline.
• Caching: Filament’s default avatar caching still applies (check filament.php under cache).
• Large SVGs: Set svgSize to a reasonable value (e.g., 500) to avoid bloated markup.

Migration Quirks

• Filament v4→v5: Run:

  php artisan vendor:publish --tag=filament-svg-avatar-core-overrides --force
  

• Laravel 11→12/13: Update dependencies and clear cached views:

  php artisan view:clear