Getting Started

Minimal Setup

Installation:

composer require livewire/flux

For Pro components:

php artisan flux:activate

Include Assets: Add these directives to your main layout file (resources/views/layouts/app.blade.php):

<head>
    @fluxAppearance
    <!-- Optional: Inter font -->
    <link href="https://fonts.bunny.net/css?family=inter:400,500,600&display=swap" rel="stylesheet" />
</head>
<body>
    @fluxScripts
</body>

Tailwind Configuration: Update resources/css/app.css:

@import 'tailwindcss';
@import '../../vendor/livewire/flux/dist/flux.css';

@theme {
    --font-sans: Inter, sans-serif;
}

First Use Case: Button Component

<x-flux.button wire:click="submitForm">
    Submit
</x-flux.button>

Implementation Patterns

1. Component Integration

Free Components: Use <x-flux.button>, <x-flux.dropdown>, etc., directly in Blade views.
Pro Components: Require activation via php artisan flux:activate (e.g., <x-flux.modal>).

2. Dynamic Styling

Leverage Tailwind classes and Flux props for consistency:

<x-flux.button variant="outline" color="blue">
    Click Me
</x-flux.button>

Common Props:

variant: primary, outline, text, ghost
color: blue, gray, red, green, etc.
size: sm, md, lg

3. Form Handling

Use wire:model with Flux inputs:

<x-flux.input wire:model="email" label="Email" />

Advanced Form Patterns:

Validation: Flux auto-applies error states via wire:model errors.

Loading States: Use wire:loading for async feedback:

<x-flux.button wire:click="submit" wire:loading.remove>
    Submit
</x-flux.button>

4. Modals and Overlays

Pro-only components like <x-flux.modal> require activation:

<x-flux.modal wire:model="showModal">
    <x-slot name="title">Confirm Action</x-slot>
    <p>Are you sure?</p>
    <x-slot name="footer">
        <x-flux.button wire:click="confirm">Yes</x-flux.button>
    </x-slot>
</x-flux.modal>

5. Dark Mode Support

Flux supports dark mode via Tailwind’s dark: variants. Ensure your layout includes:

<div class="dark:bg-gray-900 dark:text-white">
    <!-- Content -->
</div>

6. Customization Workflow

Publish Components:
```
php artisan flux:publish
```
Select components to override (e.g., button, dropdown).

Extend Styles: Override Flux CSS in resources/css/app.css:

@layer components.button {
    @apply bg-custom-blue;
}

Gotchas and Tips

Common Pitfalls

Missing @fluxAppearance or @fluxScripts:
- Symptoms: Components render but lack styles/scripts.
- Fix: Ensure directives are in <head>/<body> of your layout.

Tailwind Conflicts:

Flux uses Tailwind v4+. Ensure your tailwind.config.js matches:

module.exports = {
    darkMode: 'class',
    theme: {
        extend: {},
    },
};

Pro Components Without Activation:
- Attempting to use <x-flux.modal> without php artisan flux:activate throws errors.
- Tip: Check vendor/livewire/flux/src/FluxServiceProvider.php for registered components.
Blaze Compatibility:
- Flux v2.12+ supports Blaze. For issues (e.g., modals not closing), ensure:
```
<livewire:script />
@fluxScripts
```

Debugging Tips

Console Errors:
- Check browser console for Uncaught ReferenceError (missing @fluxScripts).
- Flux logs errors to Laravel’s storage/logs/laravel.log.

Component Isolation:

Use x-data to isolate Alpine.js logic:

<x-flux.dropdown x-data="{ open: false }">
    <!-- Content -->
</x-flux.dropdown>

Extension Points

Custom Icons:

Flux uses Lucide. Extend via:

<x-flux.icon name="custom-icon" />

import { library } from '@fortawesome/fontawesome-svg-core';
import { faCustomIcon } from '@fortawesome/free-solid-svg-icons';
library.add(faCustomIcon);

Dark Mode Overrides:

Target Flux classes in app.css:

.dark .flux-button-primary {
    @apply bg-blue-700;
}

Pro Component Access:
- After activation, Pro components (e.g., <x-flux.modal>) appear in the IDE autocomplete.

Performance Quirks

Lazy-Loading:
- Flux components are lazy-loaded by default. For critical components, inline scripts:
```
@fluxScripts(components="button,modal")
```
Memory Leaks:
- Monitor for ResizeObserver loops (fixed in v2.13.1). Use Chrome DevTools > Memory tab to profile.

Localization (i18n)

Flux v2.14+ wraps aria-label strings with __() for Laravel’s translation system:
```
<x-flux.tooltip>
    {{ __('Close') }}
</x-flux.tooltip>
```
Add translations to resources/lang/en/tooltip.php:
```
return [
    'Close' => 'Close tooltip',
];
```

RTL Support

Flux auto-detects RTL via HTML dir="rtl". For issues (e.g., pagination arrows), override in CSS:
```
.rtl .flux-pagination {
    direction: rtl;
}
```

Flux Laravel Package