Customization

Flux components can be fully customized by publishing their Blade template files to your application. This gives you complete control over component markup, styling, and behavior.

Publishing Components

Use the flux:publish command to publish component templates:

php artisan flux:publish

This command provides an interactive prompt to select which components to publish.

Interactive Selection

The default mode allows you to search and select a single component:

php artisan flux:publish

# You'll see a searchable list:
# Which component would you like to publish?
# > Button
#   Dropdown
#   Input
#   Modal
#   ...

Multiple Components

Publish multiple components at once:

php artisan flux:publish --multiple

This opens a multi-select prompt where you can choose several components.

Publish All Components

Publish every component:

php artisan flux:publish --all

Publish Specific Components

Skip the prompt by specifying component names:

php artisan flux:publish button input modal

Force Overwrite

By default, the command won’t overwrite existing published components. Use --force to overwrite:

php artisan flux:publish button --force

How Publishing Works

The publish command copies component files from the Flux package to your application:

// PublishCommand.php:99-106
(new Filesystem)->ensureDirectoryExists(resource_path('views/flux'));

$components = $this->fluxComponents()
    ->intersectByKeys(array_flip($componentNames))
    ->values()
    ->flatten()
    ->unique()
    ->all();

foreach ($components as $component) {
    $this->publishComponent($component);
}

Source Locations

The command checks for components in multiple locations:

// PublishCommand.php:139-145
$sourceAsDirectory = __DIR__.'/../../stubs/resources/views/flux/'.$component;
$sourceAsFile = __DIR__.'/../../stubs/resources/views/flux/'.$component.'.blade.php';
$sourceAsProDirectory = __DIR__.'/../../../flux-pro/stubs/resources/views/flux/'.$component;
$sourceAsProFile = __DIR__.'/../../../flux-pro/stubs/resources/views/flux/'.$component.'.blade.php';

$destinationAsDirectory = resource_path('views/flux/'.$component);
$destinationAsFile = resource_path('views/flux/'.$component.'.blade.php');

Components can be:

Single files (e.g., separator.blade.php)
Directories with multiple files (e.g., button/index.blade.php, button/group.blade.php)

Published Location

All components are published to:

resources/views/flux/

For example:

resources/views/flux/
├── button/
│   ├── index.blade.php
│   └── group.blade.php
├── input/
│   ├── index.blade.php
│   ├── clearable.blade.php
│   └── viewable.blade.php
└── modal.blade.php

Available Components

The components available for publishing depend on your license:

Free Components

// PublishCommand.php:24-51
'free' => [
    'Accent' => ['accent'],
    'Avatar' => ['avatar'],
    'Badge' => ['badge'],
    'Brand' => ['brand'],
    'Breadcrumbs' => ['breadcrumbs'],
    'Button' => ['button'],
    'Callout' => ['callout'],
    'Card' => ['card'],
    'Checkbox' => ['checkbox'],
    'Dropdown' => ['dropdown', 'menu', 'navmenu'],
    'Field' => ['fieldset', 'legend', 'field', 'label', 'description', 'error'],
    'Heading' => ['heading', 'subheading', 'text', 'link'],
    'Icon' => ['icon'],
    'Input' => ['input'],
    'Layout' => ['header', 'sidebar', 'aside', 'main', 'footer', 'container', 'brand', 'profile', 'spacer'],
    'Modal' => ['modal'],
    'Navbar' => ['navbar', 'navlist'],
    'Otp' => ['otp'],
    'Radio' => ['radio'],
    'Separator' => ['separator'],
    'Select' => ['select'],
    'Skeleton' => ['skeleton'],
    'Switch' => ['switch'],
    'Textarea' => ['textarea'],
    'Tooltip' => ['tooltip'],
    'Typography' => ['heading', 'subheading', 'text', 'link'],
]

Pro Components

// PublishCommand.php:53-74
'pro' => [
    'Accordion' => ['accordion'],
    'Autocomplete' => ['autocomplete'],
    'Calendar' => ['calendar'],
    'Chart' => ['chart'],
    'Checkbox' => ['checkbox'],
    'Command' => ['command'],
    'Composer' => ['composer'],
    'Context' => ['context'],
    'Date picker' => ['date-picker'],
    'Editor' => ['editor'],
    'File upload' => ['file-upload', 'file-item'],
    'Kanban' => ['kanban'],
    'Pillbox' => ['pillbox'],
    'Popover' => ['popover'],
    'Select' => ['select'],
    'Slider' => ['slider'],
    'Tabs' => ['tabs','tab'],
    'Table' => ['table', 'pagination'],
    'Time picker' => ['time-picker'],
    'Toast' => ['toast'],
]

Pro components are only available if livewire/flux-pro is installed:

// PublishCommand.php:117-120
protected function isFluxProInstalled(): bool
{
    return InstalledVersions::isInstalled('livewire/flux-pro');
}

Customization Examples

Example 1: Custom Button Styling

Publish the button component:

php artisan flux:publish button

Edit resources/views/flux/button/index.blade.php:

@props([
    'variant' => 'outline',
    'type' => 'button',
    'size' => 'base',
])

{{-- Add custom variant --}}
@php
$variantClasses = match($variant) {
    'solid' => 'bg-blue-600 hover:bg-blue-700 text-white',
    'outline' => 'border-2 border-blue-600 text-blue-600 hover:bg-blue-50',
    'custom-gradient' => 'bg-gradient-to-r from-purple-500 to-pink-500 text-white',
    default => '',
};
@endphp

<button {{ $attributes->merge(['class' => $variantClasses]) }}>
    {{ $slot }}
</button>

Now use your custom variant:

<flux::button variant="custom-gradient">
    Gradient Button
</flux::button>

Example 2: Custom Input Behavior

Publish the input component:

php artisan flux:publish input

Add auto-uppercase behavior in resources/views/flux/input/index.blade.php:

@props([
    'type' => 'text',
    'autoUppercase' => false,
])

<input 
    type="{{ $type }}"
    {{ $autoUppercase ? 'oninput="this.value = this.value.toUpperCase()"' : '' }}
    {{ $attributes }}
/>

Use the new prop:

<flux::input wire:model="code" :auto-uppercase="true" />

Publish the modal component:

php artisan flux:publish modal

Add more size options in resources/views/flux/modal.blade.php:

@props([
    'name' => null,
    'size' => 'md',
])

@php
$sizeClasses = match($size) {
    'xs' => 'max-w-xs',
    'sm' => 'max-w-sm',
    'md' => 'max-w-md',
    'lg' => 'max-w-lg',
    'xl' => 'max-w-xl',
    '2xl' => 'max-w-2xl',
    'full' => 'max-w-full mx-4',
    default => 'max-w-md',
};
@endphp

<div class="{{ $sizeClasses }}">
    {{ $slot }}
</div>

Component Resolution Priority

Flux checks for components in this order:

Published components in resources/views/flux/
Package components in vendor/livewire/flux/stubs/resources/views/flux/
Pro package components in vendor/livewire/flux-pro/stubs/resources/views/flux/

This is configured in the service provider:

// FluxServiceProvider.php:38-45
public function bootComponentPath()
{
    // Published components (checked first)
    if (file_exists(resource_path('views/flux'))) {
        Blade::anonymousComponentPath(resource_path('views/flux'), 'flux');
    }

    // Package components (fallback)
    Blade::anonymousComponentPath(__DIR__.'/../stubs/resources/views/flux', 'flux');
}

Updating Published Components

When you update Flux, your published components won’t be automatically updated. You have two options:

Option 1: Republish with —force

Overwrite your customizations:

php artisan flux:publish button --force

Warning: This will lose your customizations!

Option 2: Manual Merge

Check the Flux changelog for component changes
Compare your published version with the new package version
Manually merge the changes

# Compare files
diff resources/views/flux/button/index.blade.php vendor/livewire/flux/stubs/resources/views/flux/button/index.blade.php

Best Practices

Only Publish What You Need

Publishing all components makes updates harder. Only publish components you actually want to customize:

# Good - targeted publishing
php artisan flux:publish button input

# Less ideal - publishing everything
php artisan flux:publish --all

Version Control

Commit published components to version control:

git add resources/views/flux/
git commit -m "Customize Flux button component"

Document Changes

Add comments to published components:

{{-- CUSTOMIZED: Added custom-gradient variant --}}
@php
$variantClasses = match($variant) {
    'custom-gradient' => 'bg-gradient-to-r from-purple-500 to-pink-500',
    // ... rest of variants
};
@endphp

Test Thoroughly

After customizing:

Test all component variants
Test in both light and dark modes
Test Livewire interactions
Test responsive behavior

Keep Backup

Before using --force, backup your customizations:

cp -r resources/views/flux resources/views/flux-backup
php artisan flux:publish button --force

Troubleshooting

Component Not Found

If you get “Component not found” errors after publishing:

Clear Blade cache: php artisan view:clear
Verify file location: resources/views/flux/[component-name]
Check file naming (must end in .blade.php)

Changes Not Appearing

If your customizations aren’t showing:

Clear view cache: php artisan view:clear
Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
Verify you’re editing the right file

Publish Command Fails

If the command shows warnings:

Skipping [button]. File already exists: resources/views/flux/button/index.blade.php

Use --force to overwrite:

php artisan flux:publish button --force

Get Started

Core Concepts

Components

Pro Components

CLI

Customization

Publishing Components

Interactive Selection

Multiple Components

Publish All Components

Publish Specific Components

Force Overwrite

How Publishing Works

Source Locations

Published Location

Available Components

Free Components

Pro Components

Customization Examples

Example 1: Custom Button Styling

Example 2: Custom Input Behavior

Component Resolution Priority

Updating Published Components

Option 1: Republish with —force

Option 2: Manual Merge

Best Practices

Only Publish What You Need

Version Control

Document Changes

Test Thoroughly

Keep Backup

Troubleshooting

Component Not Found

Changes Not Appearing

Publish Command Fails

Build docs developers (and LLMs) love

Get Started

Core Concepts

Components

Pro Components

CLI

Documentation Index

​Publishing Components

​Interactive Selection

​Multiple Components

​Publish All Components

​Publish Specific Components

​Force Overwrite

​How Publishing Works

​Source Locations

​Published Location

​Available Components

​Free Components

​Pro Components

​Customization Examples

​Example 1: Custom Button Styling

​Example 2: Custom Input Behavior

​Example 3: Custom Modal Sizes

​Component Resolution Priority

​Updating Published Components

​Option 1: Republish with —force

​Option 2: Manual Merge

​Best Practices

​Only Publish What You Need

​Version Control

​Document Changes

​Test Thoroughly

​Keep Backup

​Troubleshooting

​Component Not Found

​Changes Not Appearing

​Publish Command Fails

Build docs developers (and LLMs) love

Publishing Components

Interactive Selection

Multiple Components

Publish All Components

Publish Specific Components

Force Overwrite

How Publishing Works

Source Locations

Published Location

Available Components

Free Components

Pro Components

Customization Examples

Example 1: Custom Button Styling

Example 2: Custom Input Behavior

Example 3: Custom Modal Sizes

Component Resolution Priority

Updating Published Components

Option 1: Republish with —force

Option 2: Manual Merge

Best Practices

Only Publish What You Need

Version Control

Document Changes

Test Thoroughly

Keep Backup

Troubleshooting

Component Not Found

Changes Not Appearing

Publish Command Fails