README

Transform Filament's default authentication pages into stunning, brand-ready experiences with customizable layouts, media backgrounds, and theme switching.

Note: This package supports Filament v4 and v5.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Media Positioning
• Global Defaults
• Custom Page Classes
• Media Configuration
• Theme Toggle
• Configuration Examples
• Render Hooks
• Troubleshooting
• Testing
• License

Features

• 🎨 Flexible Media Positioning - Place media on any side (Left, Right, Top, Bottom) or as a fullscreen cover
• 📐 Custom Sizing - Set media size with any CSS unit (%, px, vh, etc.)
• 🖼️ Media Backgrounds - Support for both images and videos with auto-detection
• 🌫️ Blur Effects - Configurable blur intensity (0-20) for Cover position
• 🌓 Theme Toggle - Built-in light/dark/system theme switcher
• 📍 Positionable Theme Toggle - Place theme switcher in any corner
• 🔧 Global Defaults - Set defaults that apply to all auth pages
• 🎯 Per-Page Overrides - Override defaults for specific pages
• 🧩 Panel-Scoped Config - In multi-panel apps, each panel keeps its own auth designer configuration
• 🔌 Custom Page Classes - Use your own page classes with the plugin's layouts
• 🪝 Render Hooks - Inject custom content at specific positions in layouts
• ♿ Accessibility - Alt text support for media
• 🚪 Email Verification Logout - Easy account switching from verification page
• ⚡ Zero Configuration - Works out of the box with sensible defaults

Requirements

• PHP 8.2+
• Laravel 11.0, 12.0, or 13.0
• Filament 4.0 or 5.0

Installation

composer require caresome/filament-auth-designer

Quick Start

Add to your Panel Provider (e.g., app/Providers/Filament/AdminPanelProvider.php):

use Caresome\FilamentAuthDesigner\AuthDesignerPlugin;
use Caresome\FilamentAuthDesigner\Data\AuthPageConfig;
use Caresome\FilamentAuthDesigner\Enums\MediaPosition;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(
            AuthDesignerPlugin::make()
                ->login(fn (AuthPageConfig $config) => $config
                    ->media(asset('assets/background.jpg'))
                    ->mediaPosition(MediaPosition::Cover)
                    ->blur(8)
                )
        );
}

Media Positioning

Use MediaPosition to control where your media appears:

Default Behavior

• No media → Minimal centered form
• Media without position → Defaults to Cover
• Cover position → mediaSize() is ignored (fullscreen)

Position Examples

Left Position (Split-style)

use Caresome\FilamentAuthDesigner\Enums\MediaPosition;

->login(fn ($config) => $config
    ->media(asset('assets/image.jpg'))
    ->mediaPosition(MediaPosition::Left)
    ->mediaSize('50%') // Media takes 50% width
)

Right Position

->login(fn ($config) => $config
    ->media(asset('assets/image.jpg'))
    ->mediaPosition(MediaPosition::Right)
    ->mediaSize('40%')
)

Top Position (Banner-style)

->login(fn ($config) => $config
    ->media(asset('assets/banner.jpg'))
    ->mediaPosition(MediaPosition::Top)
    ->mediaSize('250px') // Banner height
)

Bottom Position

->login(fn ($config) => $config
    ->media(asset('assets/footer.jpg'))
    ->mediaPosition(MediaPosition::Bottom)
    ->mediaSize('200px')
)

Cover Position (Overlay-style)

->login(fn ($config) => $config
    ->media(asset('assets/fullscreen.jpg'))
    ->mediaPosition(MediaPosition::Cover)
    ->blur(8) // Optional: 0-20
)

Size Units

Use any valid CSS unit for mediaSize():

->mediaSize('400px')   // Pixels
->mediaSize('30vh')    // Viewport height
->mediaSize('20rem')   // Rem units

Global Defaults

Set defaults that apply to all auth pages, then override specific pages as needed:

AuthDesignerPlugin::make()
    ->defaults(fn ($config) => $config
        ->media(asset('assets/default-bg.jpg'))
        ->mediaPosition(MediaPosition::Cover)
        ->blur(8)
    )
    ->login() // Uses defaults
    ->registration() // Uses defaults
    ->passwordReset(fn ($config) => $config
        ->mediaPosition(MediaPosition::Left) // Override position
        ->mediaSize('45%')
    )
    ->emailVerification() // Uses defaults
    ->themeToggle()

Custom Page Classes

Use your own custom auth page classes while keeping the plugin's layout features. This is useful when you need to customize the form (e.g., using username instead of email).

Option 1: Extend the Plugin's Page

use Caresome\FilamentAuthDesigner\Pages\Auth\Login;

class CustomLogin extends Login
{
    public function form(Schema $schema): Schema
    {
        return $schema->components([
            TextInput::make('username')->label('Username')->required(),
            $this->getPasswordFormComponent(),
            $this->getRememberFormComponent(),
        ]);
    }

    protected function getCredentialsFromFormData(array $data): array
    {
        return [
            'username' => $data['username'],
            'password' => $data['password'],
        ];
    }
}

// In your panel provider:
AuthDesignerPlugin::make()
    ->login(fn ($config) => $config
        ->media(asset('assets/login-bg.jpg'))
        ->mediaPosition(MediaPosition::Cover)
        ->usingPage(CustomLogin::class)
    )

Option 2: Use the Trait Directly

use Caresome\FilamentAuthDesigner\Concerns\HasAuthDesignerLayout;
use Filament\Auth\Pages\Login;

class CustomLogin extends Login
{
    use HasAuthDesignerLayout;

    protected function getAuthDesignerPageKey(): string
    {
        return 'login';
    }

    // Your customizations...
}

// In your panel provider:
AuthDesignerPlugin::make()
    ->login(fn ($config) => $config
        ->usingPage(CustomLogin::class)
    )

Media Configuration

Images

Supported formats: .jpg, .jpeg, .png, .webp, .gif, .svg, .avif

->login(fn ($config) => $config
    ->media(asset('assets/background.jpg'))
)

Videos

Supported formats: .mp4, .webm, .mov, .ogg

Videos auto-play, loop continuously, and are muted by default.

->login(fn ($config) => $config
    ->media(asset('assets/video.mp4'))
)

Alt Text (Accessibility)

->login(fn ($config) => $config
    ->media(asset('assets/background.jpg'), alt: 'Company branding image')
)

Theme Toggle

Enable light/dark/system theme switcher:

->themeToggle() // Default: Top Right (1.5rem)
->themeToggle(bottom: '2rem', right: '2rem') // Custom position
->themeToggle(top: '1rem', left: '1rem') // Top Left

You can position the theme switcher anywhere on the screen by passing top, bottom, left, or right CSS values. Defaults to auto if not specified.

You can also override the theme switcher position for specific pages:

->login(fn ($config) => $config
    ->themeToggle(bottom: '2rem', left: '2rem')
)

Configuration Examples

Simple - Same Layout for All Pages

AuthDesignerPlugin::make()
    ->defaults(fn ($config) => $config
        ->media(asset('assets/auth-bg.jpg'))
        ->mediaPosition(MediaPosition::Cover)
        ->blur(10)
    )
    ->login()
    ->registration()
    ->passwordReset()
    ->emailVerification()
    ->themeToggle()

Advanced - Different Layout Per Page

AuthDesignerPlugin::make()
    ->defaults(fn ($config) => $config
        ->media(asset('assets/default-bg.jpg'))
        ->mediaPosition(MediaPosition::Right)
        ->mediaSize('50%')
    )
    ->login(fn ($config) => $config
        ->media(asset('assets/login.jpg'), alt: 'Welcome back')
        ->mediaPosition(MediaPosition::Cover)
        ->blur(8)
    )
    ->registration(fn ($config) => $config
        ->media(asset('assets/register.jpg'))
        ->mediaPosition(MediaPosition::Left)
        ->mediaSize('45%')
    )
    ->passwordReset(fn ($config) => $config
        ->media(asset('assets/reset.jpg'))
        ->mediaPosition(MediaPosition::Top)
        ->mediaSize('200px')
    )
    ->emailVerification() // Uses defaults
    ->profile(fn ($config) => $config
        ->media(asset('assets/profile-bg.jpg'))
        ->mediaPosition(MediaPosition::Right)
    )
    ->themeToggle(bottom: '2rem', right: '2rem')

Available Methods

Configuration Options

Render Hooks

Inject custom Blade content at specific positions within auth layouts:

use Caresome\FilamentAuthDesigner\View\AuthDesignerRenderHook;

AuthDesignerPlugin::make()
    ->login(fn ($config) => $config
        ->media(asset('images/login-bg.jpg'))
        ->mediaPosition(MediaPosition::Cover)
        ->renderHook(AuthDesignerRenderHook::CardBefore, fn () => view('auth.branding'))
    )

Available Hook Positions

Note: CardBefore and CardAfter are specific to the Cover layout where the form is inside a card. For other layouts (Left, Right, etc.), where the form is not inside a card, use Filament's native render hooks:

• PanelsRenderHook::AUTH_LOGIN_FORM_BEFORE
• PanelsRenderHook::AUTH_LOGIN_FORM_AFTER
• PanelsRenderHook::Footer

Hook Examples

Add branding above the login card (Cover position):

->login(fn ($config) => $config
    ->renderHook(AuthDesignerRenderHook::CardBefore, fn () => view('auth.branding'))
)

Add company logo overlay on media:

->login(fn ($config) => $config
    ->renderHook(AuthDesignerRenderHook::MediaOverlay, fn () => view('auth.logo-overlay'))
)

Multiple hooks at the same position:

->login(fn ($config) => $config
    ->renderHook(AuthDesignerRenderHook::CardBefore, fn () => view('auth.logo'))
    ->renderHook(AuthDesignerRenderHook::CardBefore, fn () => view('auth.welcome-message'))
)

Troubleshooting

Images not displaying:

• Verify asset path: asset('path/to/image.jpg')
• Ensure files are in public/ directory
• Clear cache: php artisan cache:clear
• Check browser console for 404 errors

Layout not applying:

• Clear view cache: php artisan view:clear
• Verify enum usage: MediaPosition::Cover (not string)
• Check plugin is registered in panel provider

Videos not auto-playing:

• Ensure format is supported (mp4, webm, mov, ogg)
• Check browser autoplay policies
• Test in different browsers

Blur effect not working:

• Value must be between 0-20
• Some older browsers may not support backdrop-filter

Custom page not using layout:

• Ensure your custom page uses HasAuthDesignerLayout trait
• Or extend the plugin's page class
• Verify you're using ->usingPage() in the config

Media size not applying:

• mediaSize() is ignored for Cover position
• Ensure you're using a valid CSS unit

Testing

composer test          # Run tests
composer analyse       # Run PHPStan
composer format        # Format code with Pint

License

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