PHPackages                             agenticmorf/fluxui-avatar - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. agenticmorf/fluxui-avatar

ActiveLibrary[Utility & Helpers](/categories/utility)

agenticmorf/fluxui-avatar
=========================

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

v1.0.0(1mo ago)00MITPHPPHP ^8.2CI passing

Since Apr 17Pushed 1mo agoCompare

[ Source](https://github.com/AgenticMorf/fluxui-avatars)[ Packagist](https://packagist.org/packages/agenticmorf/fluxui-avatar)[ Docs](https://github.com/AgenticMorf/fluxui-avatars)[ RSS](/packages/agenticmorf-fluxui-avatar/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (12)Versions (3)Used By (0)

FluxUI Avatar
=============

[](#fluxui-avatar)

[![Tests](https://github.com/AgenticMorf/fluxui-avatars/actions/workflows/tests.yml/badge.svg)](https://github.com/AgenticMorf/fluxui-avatars/actions/workflows/tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/48f38fba8f43399a7a245e4500c933a12dbdc0b4b2f25727132fb64983c0bfd6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6167656e7469636d6f72662f666c757875692d6176617461722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/agenticmorf/fluxui-avatar)[![License](https://camo.githubusercontent.com/eb408801610ad76fd7ad7f834c0ba917950d93a5eb985f770f75ce5552726711/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6167656e7469636d6f72662f666c757875692d6176617461722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/agenticmorf/fluxui-avatar)

A drop-in, highly configurable **Avatar Manager** for Laravel applications using [Livewire 4](https://livewire.laravel.com) and [Flux UI](https://fluxui.dev).

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

[](#what-it-does)

- 🖼️ **Display** — Automatically resolves the authenticated user's avatar everywhere `` is used, with a graceful fallback to auto-generated initials.
- ⬆️ **Upload** — A ready-to-use `` 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
------------

[](#requirements)

DependencyVersionPHP`^8.2`Laravel`^11.0`Livewire`^4.0`Flux UILatest starter kit---

Installation
------------

[](#installation)

Install via Composer:

```
composer require agenticmorf/fluxui-avatar
```

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

### Publish the Config

[](#publish-the-config)

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

This creates `config/fluxui-avatar.php`.

---

Configuration
-------------

[](#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

[](#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
-----

[](#usage)

### Drop the Component Into Your Profile Page

[](#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`):

```

```

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

### The Header Avatar "Just Works"

[](#the-header-avatar-just-works)

Anywhere in the Flux UI starter kit that renders ``, 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
---------------------------------------

[](#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 ``, 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 `` 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 ``
-----------------------------------

[](#available-props-for-fluxavatar)

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](https://fluxui.dev/components/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
-------

[](#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
---------

[](#changelog)

Please see [CHANGELOG.md](CHANGELOG.md) for recent changes.

---

License
-------

[](#license)

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

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance89

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 50% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

54d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/bdadda5dda1f5a9711517509d5e552a699cd17fdac70fcc0ce7d364697d9cf0f?d=identicon)[ChrisThompsonTLDR](/maintainers/ChrisThompsonTLDR)

---

Top Contributors

[![ChrisThompsonTLDR](https://avatars.githubusercontent.com/u/348801?v=4)](https://github.com/ChrisThompsonTLDR "ChrisThompsonTLDR (1 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (1 commits)")

---

Tags

laravellivewireavatarfile-uploadflux-ui

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/agenticmorf-fluxui-avatar/health.svg)

```
[![Health](https://phpackages.com/badges/agenticmorf-fluxui-avatar/health.svg)](https://phpackages.com/packages/agenticmorf-fluxui-avatar)
```

###  Alternatives

[livewire/flux

The official UI component library for Livewire.

9466.8M119](/packages/livewire-flux)[laravel/ai

The official AI SDK for Laravel.

9782.1M153](/packages/laravel-ai)[moonshine/moonshine

Laravel administration panel

1.3k239.9k72](/packages/moonshine-moonshine)[masmerise/livewire-toaster

Beautiful toast notifications for Laravel / Livewire.

509602.4k7](/packages/masmerise-livewire-toaster)[venturedrake/laravel-crm

A free open source CRM built as a package for laravel projects

39910.0k](/packages/venturedrake-laravel-crm)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.2k](/packages/tomshaw-electricgrid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)