Laraliveui Laravel Package

Getting Started

Before you run composer require, verify your stack. LaraLiveUI is a hard fork of FluxUI v2's component API and requires Laravel 10+, Livewire 3.5.19+, and Tailwind CSS v4. If you're on Tailwind v3, stop here — the bundled dist/laraliveui.css uses v4 @import semantics and the @custom-variant directive, so there's no graceful degradation.

composer require elnasnato/laraliveui

Then wire it into the layout in three places — this is the part people get wrong most often:

<head>
    @laraliveuiAppearance
    @vite(['resources/css/app.css'])
</head>
<body>
    ...
    @livewireScripts
    @laraliveuiScripts
</body>

And import the compiled CSS into your app stylesheet:

/* resources/css/app.css */
@import 'tailwindcss';
@import '../../vendor/elnasnato/laraliveui/dist/laraliveui.css';

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

The @custom-variant dark line is not optional — components rely on class-based dark mode, and omitting it silently disables every dark: style in the library.

Where to look first. The Docusaurus site (https://elnasnato.github.io/laraliveui-docs/) is the canonical reference, but given the package's maturity (0 dependents, single-maintainer), treat the source as the real documentation: vendor/elnasnato/laraliveui/stubs/resources/views/laraliveui/ is where every Blade component lives, and reading a component's props directly is faster than guessing. Grep for @props in that directory to get an instant prop inventory.

First use case. The highest-ROI pilot is an admin CRUD screen: one <laraliveui:table>, a <laraliveui:modal> with a form inside, and <laraliveui:button> / <laraliveui:input> / <laraliveui:select>. That exercises the props API, the Livewire reactivity wiring, the asset directives, and the Tailwind integration all at once — if all five render correctly with styles, the install is sound.

Implementation Patterns

Treat the laraliveui: namespace as your design system boundary. The pragmatic pattern is to never use laraliveui: directly in feature views. Instead, create thin app-level wrappers (resources/views/components/ui/button.blade.php etc.) that delegate to the library. This gives you a single seam to swap the package, patch a variant, or add a product-specific prop without a find-and-replace across hundreds of views — critical when the upstream is a one-person project.

{{-- resources/views/components/ui/button.blade.php --}}
<laraliveui:button {{ $attributes->merge(['variant' => 'primary']) }}>
    {{ $slot }}
</laraliveui:button>

Livewire binding goes on the component tag, not inside it. Because these are Blade components that render a native <input>, wire:model must live on the component invocation:

<laraliveui:input name="email" wire:model.blur="email" placeholder="Email" />

If a component swallows attributes instead of forwarding them (check {{ $attributes }} in the stub), wire:model will silently no-op — the field renders, typing works, but the Livewire property never updates. This is the single most common "it's broken" report with component libraries of this shape; verify attribute forwarding on your first form before building further.

Compose overlays declaratively. The modal/dropdown/popover/menu components use sub-component slots rather than a JS API, which keeps them fully server-rendered and Livewire-friendly:

<laraliveui:modal name="delete-user">
    <laraliveui:modal.trigger>
        <laraliveui:button variant="danger" size="sm">Delete</laraliveui:button>
    </laraliveui:modal.trigger>
    <laraliveui:modal.dialog>
        <laraliveui:heading level="2">Confirm deletion</laraliveui:heading>
        <laraliveui:text>This action cannot be undone.</laraliveui:text>
        <laraliveui:button wire:click="delete" variant="danger">Confirm</laraliveui:button>
    </laraliveui:modal.dialog>
</laraliveui:modal>

Open/close from PHP via the window.LaraLiveUI namespace (not Flux) if you need programmatic control after a Livewire action:

$this->dispatch('modal-show', name: 'delete-user'); // if the component listens

Verify the actual event name in dist/laraliveui.js before relying on it — the JS API surface is the least-documented part of the package.

Scaffold layouts early. Layout (Header, Sidebar, Main, Footer), Navbar, and Navlist are the pieces that save the most time. Build your skeleton once (collapsible sidebar + sticky header + main) and every subsequent page is a two-line diff.

Publish only when you must. php artisan laraliveui:publish copies Blade stubs into your app so you can edit them. Use it surgically — publish a single component you need to change, not the whole tree, because published files are frozen at the version you published them at and will silently diverge from upstream on composer update.

Icons are just components. 300+ Heroicons ship as <laraliveui:icon name="..." variant="solid|outline" />. They accept class for color/sizing, so you can drop them anywhere Tailwind classes work. Keep a constants file or enum of the icon names you use to avoid typos producing blank renders.

Migrating from FluxUI is mechanical. Use a scoped sed across resources/views rather than hand-editing:

grep -rl 'flux:' resources/views | xargs sed -i \
  -e 's/<flux:/<laraliveui:/g' \
  -e 's|</flux:|</laraliveui:|g' \
  -e 's/@fluxScripts/@laraliveuiScripts/g' \
  -e 's/@fluxAppearance/@laraliveuiAppearance/g'

Then grep for \$flux, data-flux-, --flux-, and window.Flux — the Alpine store is $laraliveui, and stale $flux references will fail at runtime, not at compile time.

Gotchas and Tips

Pin the version explicitly. With zero dependents and no enterprise backing, composer require at * is a liability. Use "elnasnato/laraliveui": "1.0.*" and review the diff on every minor bump. Note the version inconsistency in the source material: the README and release notes reference v2.0.0, while the project's own AGENTS.md lists v1.0.4 as latest. Confirm what composer show elnasnato/laraliveui actually resolves to before assuming an API surface.

Asset directive ordering matters. @laraliveuiScripts must come after @livewireScripts — the package's JS assumes Livewire and Alpine are already on the page. Put it before and you get "Alpine is not defined" or silently dead interactive components with no console error in production builds.

CSS not applying? Walk this checklist in order:

1. Is the @import path exactly ../../vendor/elnasnato/laraliveui/dist/laraliveui.css relative to resources/css/app.css? (Note the vendor is elnasnato, not laralive — this trips people up.)
2. Did you rebuild with npm run build / npm run dev after adding the import?
3. Is @custom-variant dark present?
4. php artisan view:clear && php artisan optimize:clear — compiled Blade caches component resolution.
5. Check the rendered HTML for data-laraliveui-* attributes. Present but unstyled = CSS problem; absent = component resolution problem.

The "pro" components are a licensing gray area. The project is explicitly a clone of FluxUI v2, including the 18 pro-tier groups. Before shipping to production, confirm with stakeholders that this is acceptable for your context — the MIT license on this repo does not necessarily launder the design/API provenance of the components it reimplements. For internal tools this is usually a non-issue; for a commercial product, get a sign-off.

Accessibility is unverified. There's no indication of WCAG audit or automated a11y tests. If you have compliance requirements, budget time to keyboard-test every overlay (focus trap on modal, escape-to-close, arrow-key nav in dropdown/menu) and add ARIA attributes yourself. Do not assume.

Debugging interactive components. When a modal won't open, the failure is almost always one of: (a) scripts not loaded, (b) @laraliveuiScripts in the wrong position, (c) the name prop missing or duplicated across the page. Duplicate modal names are a real footgun in loops — generate them from the model ID (name="edit-user-{{ $user->id }}").

Test the seams, not the library. Don't write Livewire tests asserting on LaraLiveUI's markup — it'll churn. Test that your Livewire actions fire, and use assertSee on user-visible strings only. For overlay behavior, a handful of Dusk/browser tests covering open/close/submit on your three or four most critical flows is enough coverage for a dependency you don't control.

Extension points, in order of safety: (1) pass class through to the component; (2) wrap it in your own component; (3) publish and edit the stub; (4) fork. Options 1–2 survive composer update; 3 does not; 4 means you now maintain a UI library. Stay at 1–2 as long as humanly possible.

Have an exit plan. Before adopting, confirm the effort to revert: if your wrapper components are the only place laraliveui: appears, swapping to FluxUI, SheafUI, or hand-rolled Tailwind is a day's work. If you used laraliveui: directly in 200 views, it's a week. The wrapper pattern isn't ceremony — it's the insurance policy that makes adopting an unproven package a reversible decision.