Cascader Laravel Package

This release fixes every finding from a full package audit (#1–#12, PR #13). If you are on v0.4.0 or earlier, upgrade — the component's core feature was broken.

Highlights

wire:model works again (#1). Since the wire:model rewrite in December, the Blade template and the Alpine component spoke different APIs: the entangle object was silently discarded, so selections never synced to Livewire, selected-state highlights and the clear button never rendered, and pre-selected values showed the placeholder. The Alpine component now owns a single modelValue (selectedValue remains as a deprecated alias), derives the trigger label from the options, and follows server-side changes. The selected-text prop and the deprecated wire-model prop work again.

Icon rendering hardened (#2). Icon names and colors are no longer concatenated into Blade template source — components render through x-dynamic-component with values passed as data, names are validated, colors sanitized, and rendered icons are memoized per request.

Also fixed

• Escape clears the search first instead of closing the whole dropdown (#3)
• wire:model.live.debounce.500ms-style modifier chains detected correctly; no more attribute leaking onto the root element (#4)
• Full dark mode for the dropdown panel, search, and mobile sheet (#5)
• Leaf-only search results ("Parent / Child" paths), matching the cascade's selection rules (#6)
• No more crash when options lack their label field; label-field takes priority; 0 is a valid value (#7)
• Window listeners cleaned up on destroy — fixes a leak with wire:navigate (#8)
• Stale hover state after Escape, non-hex icon colors via color-mix(), breakpoint-crossing handling (#9)

Packaging & infrastructure

• illuminate/view/illuminate/contracts declared as dependencies (#10)
• README rewritten for the current API, including the required Alpine registration step (#11)
• Test suite (17 tests) + CI across PHP 8.2–8.4 × Laravel 11–13, and this changelog (#12)

Upgrading from ≤ 0.4.0

• If you use the Blade component: no changes needed — wire:model (and the old wire-model prop) now actually work.
• If you use the Alpine component directly: rename the selectedValue param to modelValue (the old name still works but is deprecated).
• Register the Alpine component if you hadn't — see the README's installation section; this step was previously undocumented.

Full details in CHANGELOG.md.

Full Changelog: https://github.com/vlados/cascader/compare/v0.3.0...v0.4.0

What's New

• Size variants: New size prop with sm (default) and xs options
• Flux UI styling: Matches Flux select component appearance
• Dark mode: Full dark mode support with dark: class variants
• Improved binding: Uses $wire.entangle() for cleaner Livewire two-way binding
• Flexible dropdown: Uses min-width instead of fixed width

Added

• Support for standard wire:model syntax (wire:model, wire:model.live, wire:model.blur, wire:model.debounce)
• Uses hidden input for Livewire binding (cleaner approach)

Changed

• Legacy wire-model prop still works for backward compatibility

Fixed

• Dropdown visibility in modals: The desktop dropdown now uses x-teleport to escape overflow: hidden containers (like modals), ensuring it's always visible above all content
• Dynamic position tracking: Added scroll and resize listeners to keep the dropdown aligned with the trigger button when teleported

Fixes

• Increase dropdown z-index to z-[99999] for better modal compatibility

Fixes

• Fix dropdown appearing behind modals by teleporting to body with z-[9999]
• Add dynamic position tracking on open, scroll, and resize
• Fix Enter key in search input triggering parent form submission (v0.2.2)

New Features

Blade FontAwesome Support

New useBladeFontAwesome() resolver for projects using the blade-fontawesome package:

use Vlados\Cascader\IconResolver;

IconResolver::useBladeFontAwesome(); // renders <x-fas-{icon} />
IconResolver::useBladeFontAwesome('far'); // renders <x-far-{icon} />

Improved Error Messages

When an icon component cannot be found, you now get a clear, actionable error:

Cascader: Unable to render icon component '<x-fas-missing />'.
Original icon name: 'missing'.
Make sure the icon exists or configure a different IconResolver.
Available resolvers: useFontAwesome(), useBladeFontAwesome(), useHeroicons(), useBladeIcons(), or using() for custom.

Available Resolvers

New Features

Flexible Icon Resolver System

The cascader now supports multiple icon libraries through a resolver system:

• FontAwesome (default) - IconResolver::useFontAwesome()
• Heroicons - IconResolver::useHeroicons()
• Blade Icons - IconResolver::useBladeIcons()
• Custom resolver - IconResolver::using(fn($icon, $color, $size) => ...)

Example Usage

// In AppServiceProvider::boot()
use Vlados\Cascader\IconResolver;

// Use Heroicons instead of FontAwesome
IconResolver::useHeroicons('outline');

// Or create a custom resolver
IconResolver::using(function (string $icon, ?string $color, string $size) {
    return view('components.my-icon', compact('icon', 'color', 'size'))->render();
});

Other Changes

• Icons are now pre-resolved server-side for better performance
• Updated blade template to use x-html for dynamic icon rendering

Features

• Two-column cascading dropdown (desktop)
• Mobile-friendly bottom sheet with step-by-step navigation
• Search/filter through all options
• Clearable selection with optional clear button
• Icons and colors support (FontAwesome)
• Selected value shows "Parent / Child" format
• Configurable value and label fields
• Customizable Cancel/Confirm button text (mobile)
• Works with Livewire's wire:model

Requirements

• PHP 8.2+
• Laravel 11 or 12
• Livewire 3
• Alpine.js 3
• Tailwind CSS