Flux Laravel Package

Getting Started

Flux ships two packages: livewire/flux (free tier — Button, Dropdown, Icon, Separator, Tooltip, plus a growing list of "starter" components like Card, Table, Paginator, Checkbox/Radio variants as of v2.11) and livewire/flux-pro (everything else — Modal, Select, DatePicker, Tabs, Sidebar, Charts, Kanban, Editor, Composer, etc.). Audit what you actually need before you install, because the free tier is genuinely narrow.

Prerequisites (all hard requirements, not suggestions):

• Laravel 10+
• Livewire 3.5.19+
• Tailwind CSS v4 — Flux's CSS is written against v4's @theme/@custom-variant syntax and will not work with a v3 pipeline.

Install and wire up:

composer require livewire/flux

Then in your root layout (resources/views/components/layouts/app.blade.php typically):

<head>
    @fluxAppearance
</head>
<body>
    {{ $slot }}
    @fluxScripts
</body>

@fluxAppearance must be in <head> — it's what applies the stored dark-mode class before paint and prevents the flash. @fluxScripts goes at the end of <body>.

Then in resources/css/app.css:

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

@custom-variant dark (&:where(.dark, .dark *));

The @custom-variant dark line is not optional boilerplate — without it, Flux's dark styles never activate even if you toggle the .dark class on <html>.

First use case: build a simple form with flux:button and flux:icon inside a Livewire component. This is the smallest path that proves assets, CSS, and Blade directives are all wired correctly before you commit to a Pro purchase:

<flux:button variant="primary" icon="plus" wire:click="create">
    New Project
</flux:button>

If the button renders unstyled or the icon is missing, stop and fix the CSS import before going further — 90% of "Flux isn't working" reports are a broken flux.css import or a missing Tailwind v4 pipeline.

Pro activation (if licensed):

php artisan flux:activate

This stores credentials locally; the license check is baked into the package via ensurePro. If Pro components render as placeholders or throw, re-run activation and confirm livewire/flux-pro is actually in composer.json — it's a separate package and easy to forget.

Where to look first: the docs at fluxui.dev/docs, not the GitHub README. The README covers install only; every component has a dedicated docs page with props, slots, and Livewire binding examples. Bookmark the component index — you'll be checking which tier a component belongs to constantly.

Implementation Patterns

Treat Flux as your design system, not a component grab-bag. The patterns that pay off:

App shell with flux:sidebar (Pro). The canonical Laravel layout upgrade is replacing hand-rolled nav with flux:sidebar, flux:sidebar.nav, flux:sidebar.item, and flux:header. You get responsive collapse, mobile drawer behavior, and wire:navigate integration for free. The flux:brand component accepts logo and logo:dark (added v2.10) for theme-aware branding — use both or your sidebar looks broken in dark mode.

Form fields via wire:model, not manual wiring. Flux form components are Livewire-native first. flux:select, flux:input, flux:date-picker, flux:time-picker, flux:otp, and flux:checkbox.group all bind directly:

<flux:select wire:model="status" label="Status" placeholder="Choose...">
    <flux:select.option value="draft">Draft</flux:select.option>
    <flux:select.option value="published">Published</flux:select.option>
</flux:select>

Notable: flux:select forwards a real native <select> value for native form submission (fixed in v2.11), so it works both inside Livewire and in a plain <form> POST. Same for flux:pillbox. That means you can use Flux in a non-Livewire context — e.g., login forms or marketing pages — without rewriting.

Modals driven by Livewire state. Declare the modal in the component, control it with wire:model on a boolean, and put the trigger and content in the same Blade file:

<flux:modal wire:model="showModal" class="max-w-md">
    <flux:heading>Edit project</flux:heading>
    ...
</flux:modal>

Modals do work outside a Livewire component (v2.11.1 fixed this), but the ergonomic pattern — toggling from a Livewire action, closing on submit — depends on the component context. Keep them inside.

Customize by publishing, but do so sparingly. php artisan flux:publish prompts for individual components; --all dumps everything. The integration tip that matters: publish only the components you actually need to change. Every published Blade file is a future merge conflict against composer update. If you just want to change a color, do it with a CSS variable or a Tailwind class in your layout first.

Theming via CSS variables, not overrides. Flux exposes design tokens you can override in your app.css @theme block:

@theme {
    --font-sans: Inter, sans-serif;
    --color-accent-500: oklch(0.6 0.2 260);
}

This survives updates cleanly. php artisan flux:publish does not.

Toast + flash pattern. flux:toast.group in your layout plus flux:toast dispatched from a Livewire action is the standard post-save confirmation. Watch the z-index stacking against modals — the "toast group behind modal" fix landed in v2.9 but ordering still matters if you've customized stacking contexts.

Tables with flux:table + flux:paginator. These became free in v2.11, so you can build admin tables without a license. Wire sorting/selection to Livewire properties (wire:model on flux:table.row, sortable columns). Note: "Allow forcing of data-current in links" was reverted and then restored (2.10.1 → 2.10.2) — if you're on a brief window of 2.10.1, current-link highlighting behaves inconsistently. Pin past it.

Charts for dashboards. flux:chart (Pro) got bar charts in v2.12 and a locale prop in v2.9. Feed it Livewire-computed series arrays; don't try to mutate chart data client-side through JS — re-render via the component.

Icons. flux:icon wraps Heroicons. Prefer named icons (icon="pencil", icon="trash") over raw SVG; you get consistent sizing and variant="micro" / variant="mini" sizes.

Integration tip for new attributes: as of v2.13.0, an input: attribute prefix targets the inner <input> element of composite components (e.g., input:autocomplete="off"). Use this when a prop isn't exposed but you need to pass a native attribute through.

Gotchas and Tips

Free vs Pro is a moving target. The README lists five free components, but releases show card, table, paginator, checkbox variants, and all radio variants made free in v2.11.0. Don't assume the README is current for tiering — check the live docs page. Conversely, don't assume a component will stay free; the library can re-tier.

flux-pro requires Blaze. As of v2.10.0, Flux Pro requires Blaze 1.0 (bumped to 2.0 in v2.12.1). If you're managing dependencies tightly or using a package that pins an older Blaze, you'll get a composer conflict or runtime errors. Check composer why livewire/flux-pro when things break after an update. Also, Blaze + Flux has had intermittent edge cases (e.g., "Fix flux:select.selected with blaze" in v2.10, "Fix modal with Blaze" in v2.12.2) — if a Pro component misbehaves, try disabling Blaze to isolate.

Asset version skew between flux and flux-pro. They're separate packages and can drift. Always update them together:

composer update livewire/flux livewire/flux-pro

Mismatched versions produce subtle rendering bugs (missing slots, wrong variants) that look like your code.

Dark mode flash / no dark mode at all. Two distinct causes:

1. @fluxAppearance missing from <head> — you get a flash of light mode on load.
2. @custom-variant dark missing from app.css — dark mode never works at all, even with the class toggled.

There was also a "forced dark mode switch" bug fixed in v2.8.0; if you're pinning an old version and users report dark mode ignoring their toggle, that's your culprit.

CSP. Component CSP-safety landed in v2.11.0. Before that, Flux injected inline <style>/<script> and broke strict Content-Security-Policy setups. If you're on CSP and pinning below 2.11, you need nonces.

Publishing is a commitment. Each published Blade file lives in resources/views/vendor/livewire/flux/ (or similar depending on how the publish command resolves). It won't receive fixes. Before publishing, verify the change can't be done via CSS variable or a wrapping element with Tailwind classes. If you must publish, keep a comment at the top of each file naming the version it was published from.

wire:navigate flicker. Fixed in v2.11.0, but if you're below that, sidebar and header elements flash on navigation. Either upgrade or disable wire:navigate on affected links.

Scroll-lock and gutter quirks. Modal/sidebar scroll locking has been patched repeatedly — "Fix lock scroll gutter issues" (2.9.1), "Fix scrollbar-gutter on documents without scroll" (2.10.0), "Fix scrollbar-gutter with overflow: hidden" (2.11.0). If your layout jumps when a modal opens, upgrade first before writing custom CSS.

Modal z-index with popover/tooltip. "Fix popover closing inside modal" (v2.11.0). Tooltips and popovers inside modals historically had stacking issues; keep Flux updated and avoid custom z-index on your own wrappers, which will fight the component's teleported layering.

Label/slot precedence. Components with both label prop and slot content had a precedence fix in v2.12.0. If you're supplying both, test carefully — the slot wins in recent versions, but behavior differed before.

Input styling and forms plugin. Flux ships its own input styling and specifically overrides Tailwind Forms styles for the time picker (v2.9.1). Do not mix @tailwindcss/forms into the same inputs — you'll get double borders and inconsistent focus rings.

Debugging: publish one component and read it. The fastest way to understand Flux's internals is php artisan flux:publish for the single component that's misbehaving, read the Blade + look for data-* hooks, then delete it. Don't leave it published.

Native form submission inside flux:select / flux:pillbox was fixed in v2.11. If you're doing non-Livewire forms on an older version, options won't submit — upgrade or add a hidden input mirroring the value.

flux:otp input events fire on programmatic updates in older versions (fixed 2.9.1) — if you set the OTP value from Livewire and get spurious updated events, you're on a version with that bug.

Extension points to know:

• @theme CSS variables — theming, colors, fonts.
• Component variant props (primary, ghost, danger, subtle) — prefer these over overriding Tailwind classes.
• input: attribute prefix (v2.13+) — pass-through attributes to inner inputs.
• data-current forcing on links and wire:current.ignore — for custom nav highlighting without relying on route matching.
• flux:modal.close with attributes — for custom close buttons.