mrshanebarron/avatar

User profile images with fallback initials for Laravel. Supports Livewire and Blade.

dev-main 2025-12-14 04:33 UTC

Requires

• php: ^8.1
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• pestphp/pest: ^2.0

MIT

• Shane Barron

• ui
• component
• laravel
• avatar
• blade
• livewire

README

User profile images with fallback initials and status indicators. Built for Laravel with support for Livewire, Blade, and Alpine.js.

Installation

composer require mrshanebarron/avatar

The service provider will be auto-discovered. If you need to register it manually:

// config/app.php
'providers' => [
    // ...
    MrShaneBarron\Avatar\AvatarServiceProvider::class,
];

Usage

Livewire Component

<livewire:ld-avatar />

Blade Component

<x-ld-avatar />

With Props

<x-ld-avatar
    size='md'
    src=null
    alt='User'
    fallback=null
    status=null
/>

Props

Prop	Type	Default	Description
size	string	'md'	Size of avatar: 'xs', 'sm', 'md', 'lg', 'xl'
src	string	null	URL of the avatar image
alt	string	'User'	Alt text for the image
fallback	string	null	Fallback text (initials) when no image
status	string	null	Status indicator: 'online', 'offline', 'away', 'busy'

Configuration

Publish the config file:

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

This will create a config/ld-avatar.php file where you can customize default values.

Customization

Publishing Views

Customize the component appearance by publishing the views:

php artisan vendor:publish --tag=ld-avatar-views

Views will be published to resources/views/vendor/ld-avatar/.

Styling

The component uses Tailwind CSS classes by default. You can customize styles by:

1. Publishing views and modifying the Blade templates
2. Using the class attribute to add custom classes
3. Overriding default styles in your CSS

<x-ld-avatar class="custom-class" />

Events

The component dispatches Livewire events you can listen to:

Event	Payload	Description
avatar:updated	Component data	Fired when state changes
avatar:initialized	Initial data	Fired on component mount

// In your Livewire component
protected $listeners = ['avatar:updated' => 'handleUpdate'];

public function handleUpdate($data)
{
    // Handle the update
}

Alpine.js Integration

The component works seamlessly with Alpine.js:

<div x-data="{ ' }} selected: null {{ ' }">
    <x-ld-avatar x-model="selected" />
    <p x-text="selected"></p>
</div>

Requirements

• PHP 8.1+
• Laravel 10.x, 11.x, or 12.x
• Livewire 3.x
• Tailwind CSS 3.x (optional, for default styling)

Testing

composer test

Changelog

Please see CHANGELOG for recent changes.

Contributing

Contributions are welcome! Please see CONTRIBUTING for details.

Security

If you discover a security vulnerability, please email [e-mail] instead of using the issue tracker.

Credits

• Shane Barron
• All Contributors

License

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