Getting Started

Minimal Setup

Installation:
```
composer require livewire/flux
```
Ensure your project meets prerequisites: Laravel 10+, Livewire 3.5.19+, Tailwind CSS 4.0+.
Include Assets: Add these directives to your layout file (e.g., resources/views/layouts/app.blade.php):
```
<head>
    @fluxAppearance
</head>
<body>
    @fluxScripts
</body>
```
First Use Case: Use a basic flux:button in a Livewire component:
```
<flux:button wire:click="submitForm">
    Submit
</flux:button>
```
Verify the button renders with Flux styling.

Quick Start Workflow

Publish Assets (if customization is needed):
```
php artisan flux:publish
```
Select components to customize (e.g., Button, Dropdown).

Test a Component: Use flux:dropdown in a Livewire component:

<flux:dropdown>
    <flux:dropdown.trigger>
        Actions
    </flux:dropdown.trigger>
    <flux:dropdown.content>
        <flux:dropdown.item wire:click="edit">Edit</flux:dropdown.item>
        <flux:dropdown.item wire:click="delete">Delete</flux:dropdown.item>
    </flux:dropdown.content>
</flux:dropdown>

Verify Tailwind Integration: Ensure resources/css/app.css includes:

@import 'tailwindcss';
@import '../../vendor/livewire/flux/dist/flux.css';
@theme { --font-sans: Inter, sans-serif; }

Pro Features (If Licensed)

Activate Pro:
```
php artisan flux:activate
```
Enter your license key when prompted.
Access Pro Components: Use components like flux:timeline or flux:chart (check FluxUI.dev for Pro-only docs).

Implementation Patterns

Component Integration

1. Form Handling

Use Flux components with Livewire form binding:

<flux:input
    wire:model="email"
    label="Email"
    placeholder="user@example.com"
    invalid={{ $errors->has('email') }}
    error-message="{{ $errors->first('email') }}"
/>

Key Attributes:
- wire:model: Bind to Livewire property.
- invalid: Toggle error state.
- error-message: Display validation errors.

2. Dynamic State Management

Leverage Livewire properties to control Flux component states:

public $isDropdownOpen = false;

<flux:dropdown x-data="{ open: @entangle('isDropdownOpen') }">
    <flux:dropdown.trigger @click="open = !open">
        Toggle
    </flux:dropdown.trigger>
    <!-- Dropdown content -->
</flux:dropdown>

3. Nested Components

Combine Flux components for complex UIs:

<flux:card>
    <flux:card.header>
        <flux:dropdown>
            <!-- Dropdown content -->
        </flux:dropdown>
    </flux:card.header>
    <flux:card.body>
        <flux:input wire:model="description" />
    </flux:card.body>
</flux:card>

Workflows

1. Data Tables

Use flux:table with Livewire pagination:

<flux:table>
    <flux:table.header>
        <flux:table.column>Name</flux:table.column>
        <flux:table.column>Status</flux:table.column>
    </flux:table.header>
    <flux:table.body>
        @foreach($items as $item)
            <flux:table.row wire:key="{{ $item->id }}">
                <flux:table.cell>{{ $item->name }}</flux:table.cell>
                <flux:table.cell>
                    <flux:badge variant="success">Active</flux:badge>
                </flux:table.cell>
            </flux:table.row>
        @endforeach
    </flux:table.body>
    <flux:table.footer>
        {{ $items->links() }} <!-- Livewire pagination -->
    </flux:table.footer>
</flux:table>

2. Modals and Forms

Create a reusable modal form:

<flux:modal wire:model="isModalOpen">
    <flux:modal.header>
        <h3>Create Item</h3>
    </flux:modal.header>
    <flux:modal.body>
        <flux:input wire:model="name" label="Name" />
        <flux:input wire:model="description" label="Description" />
    </flux:modal.body>
    <flux:modal.footer>
        <flux:button wire:click="save">Save</flux:button>
    </flux:modal.footer>
</flux:modal>

public $isModalOpen = false;
public $name;
public $description;

public function save() {
    // Handle form submission
    $this->isModalOpen = false;
}

3. Real-Time Updates

Use wire:model.live for instant feedback:

<flux:input
    wire:model.live="searchQuery"
    placeholder="Search..."
/>

public $searchQuery;

public function updatedSearchQuery($value) {
    $this->results = Model::where('name', 'like', "%{$value}%")->get();
}

Tailwind Customization

Extend Flux’s Tailwind classes in app.css:

@layer components.flux {
    .flux-button {
        @apply bg-blue-600 hover:bg-blue-700;
    }
    .flux-input {
        @apply border-gray-300 focus:border-blue-500;
    }
}

Gotchas and Tips

Pitfalls

Missing @fluxAppearance or @fluxScripts:
- Symptom: Components render without styles or JavaScript.
- Fix: Ensure directives are in <head> and <body> respectively.
Tailwind Conflicts:
- Symptom: Flux styles override your custom Tailwind classes.
- Fix: Use @layer components.flux in app.css to prioritize Flux styles or scope your customizations.
Livewire Property Binding Issues:
- Symptom: wire:model not updating or crashing.
- Fix: Ensure the Livewire property exists in your component class and is public. For null values, use:
```
<flux:select wire:model="categoryId" :options="$categories">
```
  With categoryId initialized in your component:
```
public $categoryId = null;
```
Blaze Compatibility:
- Symptom: Components not rendering with Blaze (Livewire’s new compiler).
- Fix: Update to Flux v2.12.1+ (released for Blaze 2.0 support). Ensure your app.blade.php includes:
```
@blade
```
CSP Violations:
- Symptom: Console errors about inline scripts or nonces.
- Fix: Use flux:publish to customize components and ensure nonces are included (Flux v2.11.0+ handles this).

Debugging Tips

Inspect Component Structure: Use browser dev tools to verify Flux components render the expected HTML. Look for:
- Missing data-flux-* attributes.
- Unclosed or malformed tags.
Check for JavaScript Errors:
- Open browser console (F12) and filter for flux.js errors.
- Common issues:
  - Missing Alpine.js (Flux depends on it).
  - Conflicting Alpine.js versions (ensure ^3.13.0 is used).
Validate Livewire Events:
- Ensure wire:click, wire:model, etc., are correctly bound to public methods/properties.
- Test with {{ dd($this->property) }} to verify data flow.
Tailwind Dark Mode:
- If using dark mode, ensure your app.css includes:
```
@custom-variant dark (&:where(.dark, .dark *));
```
- Test with class="dark" on the <body> or <html> tag.

Extension Points

Custom Components: Publish and modify Flux components:
```
php artisan flux:publish --all
```
Edit published files in resources/views/vendor/flux/.
Alpine.js Extensions: Extend Fl

Flux Laravel Package