agenticmorf/fluxui-avatar

A drop-in, highly configurable Avatar Manager for Laravel applications using Livewire 4 and Flux UI.

v1.0.0 2026-04-17 02:08 UTC

Requires

• php: ^8.2
• illuminate/filesystem: ^11.0
• illuminate/support: ^11.0
• livewire/livewire: ^4.0

Requires (Dev)

• larastan/larastan: *
• laravel/pint: *
• livewire/livewire: ^4.0
• orchestra/testbench: *
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/phpstan: *
• phpunit/phpunit: ^11.0

Suggests

• spatie/laravel-medialibrary: Required when using the spatie driver.

MIT

• AgenticMorf

• laravel
• avatar
• file-upload
• livewire
• flux-ui

README

A drop-in, highly configurable Avatar Manager for Laravel applications using Livewire 4 and Flux UI.

This package seamlessly handles the uploading, validating, storing, and displaying of user avatars while non-invasively injecting itself into the Flux UI Livewire Laravel starter kit. No vendor publishing. No editing starter-kit files. Just install and go.

What It Does

• 🖼️ Display — Automatically resolves the authenticated user's avatar everywhere <flux:avatar /> is used, with a graceful fallback to auto-generated initials.
• ⬆️ Upload — A ready-to-use <livewire:avatar-manager /> component with Flux UI file-upload styling, loading states, and validation.
• 🗄️ Store — Two built-in storage adapters: Laravel Filesystem (disk) and Spatie Media Library.
• 🔌 Non-invasive — View namespace shadowing means the starter kit's profile header magically shows the correct avatar without any code changes.

Requirements

Dependency	Version
PHP	^8.2
Laravel	^11.0
Livewire	^4.0
Flux UI	Latest starter kit

Installation

Install via Composer:

composer require agenticmorf/fluxui-avatar

Laravel's package auto-discovery will automatically register the service provider.

Publish the Config

php artisan vendor:publish --tag=fluxui-avatar-config

This creates config/fluxui-avatar.php.

Configuration

// config/fluxui-avatar.php

return [
    // 'spatie' or 'disk'
    'driver' => env('FLUXUI_AVATAR_DRIVER', 'disk'),

    // Spatie driver settings
    'spatie_collection_name' => 'avatars',

    // Disk driver settings
    'disk'      => env('FLUXUI_AVATAR_DISK', 'public'),
    'directory' => 'avatars',
    'column'    => 'avatar_path', // DB column on your User model

    // Validation
    'accepted_types'  => ['jpg', 'jpeg', 'png', 'webp'],
    'max_file_size'   => 2048, // in KB

    // Default avatar URL (null uses Flux UI's built-in fallback)
    'default_avatar' => null,
];

Switching Drivers

Disk driver (default): Uses Laravel's filesystem. Add avatar_path to your users table:

php artisan make:migration add_avatar_path_to_users_table

$table->string('avatar_path')->nullable();

Spatie driver: Requires spatie/laravel-medialibrary. Add HasMedia to your User model:

use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;

class User extends Authenticatable implements HasMedia
{
    use InteractsWithMedia;

    public function registerMediaCollections(): void
    {
        $this->addMediaCollection('avatars')->singleFile();
    }
}

Then update your .env:

FLUXUI_AVATAR_DRIVER=spatie

Usage

Drop the Component Into Your Profile Page

Place the Livewire component wherever you want the avatar upload form to appear (e.g., resources/views/profile.blade.php):

<livewire:avatar-manager />

That's it. The component handles everything — upload, preview, validation, removal.

The Header Avatar "Just Works"

Anywhere in the Flux UI starter kit that renders <flux:avatar />, this package's shadowed component will automatically inject the authenticated user's avatar URL. If no avatar has been uploaded, it gracefully falls back to generated initials from the user's name.

You don't need to change any starter-kit views.

Under the Hood: The View Overload Magic

Flux UI registers its components under the flux Blade namespace. Laravel resolves these components by searching all paths registered for that namespace, in order.

This package's FluxuiAvatarServiceProvider::boot() method calls:

$viewFactory->prependNamespace('flux', __DIR__.'/../resources/views/components');

prependNamespace inserts our path at the front of the namespace's path list, so when Laravel resolves <flux:avatar />, it finds our resources/views/components/avatar.blade.php first.

Our avatar.blade.php resolves the current user's avatar from the configured storage adapter, generates initials if needed, then delegates to Flux's real template (flux::avatar.index from the livewire/flux package). We cannot nest <flux:avatar> here: namespace shadowing would resolve to this same file and recurse infinitely. Including the vendor view preserves all native Flux UI avatar behavior.

Available Props for <flux:avatar>

This package augments Flux's avatar component: when src is omitted, it fills the URL (and optionally initials) from the authenticated user. All Flux Avatar props continue to work (size, circle, color, name, icon, badge, tooltip, and so on). If you pass shape="circle" or shape="square", it is mapped to Flux's circle boolean for compatibility with older examples.

Testing

# Run the full test suite
composer test

# Run with coverage report
composer test-coverage

# Run static analysis
composer analyse

# Check code style
composer format

Changelog

Please see CHANGELOG.md for recent changes.

License

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