PHPackages                             vlados/cascader - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Templating & Views](/categories/templating)
4. /
5. vlados/cascader

ActiveLibrary[Templating & Views](/categories/templating)

vlados/cascader
===============

A cascading dropdown component for Laravel Livewire with Alpine.js

v0.5.0(2w ago)0845MITBladePHP ^8.2CI passing

Since Dec 28Pushed 2w agoCompare

[ Source](https://github.com/vlados/cascader)[ Packagist](https://packagist.org/packages/vlados/cascader)[ RSS](/packages/vlados-cascader/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (10)Dependencies (10)Versions (17)Used By (0)

Cascader
========

[](#cascader)

A cascading dropdown component for Laravel Livewire with Alpine.js. Inspired by Ant Design's Cascader component.

On desktop it renders as a two-column dropdown with search; on mobile (< 640px) it becomes a bottom sheet with step-by-step navigation. Light and dark mode are both supported out of the box.

Requirements
------------

[](#requirements)

- PHP 8.2+ (Laravel 13 requires PHP 8.3+)
- Laravel 11, 12 or 13
- Livewire 3 or 4
- Alpine.js 3
- Tailwind CSS
- An icon source if you use icons (FontAwesome by default — see [Icon Resolver](#icon-resolver))

Installation
------------

[](#installation)

```
composer require vlados/cascader
```

### Register the Alpine component (required)

[](#register-the-alpine-component-required)

The Blade component renders `x-data="cascader(...)"`, so the Alpine component must be registered before Alpine starts. Publish the script and import it in your bundle:

```
php artisan vendor:publish --tag=cascader-scripts
```

```
// resources/js/app.js — before Alpine.start()
import { cascader } from './vendor/cascader/cascader';

document.addEventListener('alpine:init', () => {
    Alpine.data('cascader', cascader);
});
```

The script also registers itself automatically when it is loaded on a page where Alpine is available globally (before `alpine:init` fires), so with a plain `` setup no extra code is needed.

### Tailwind

[](#tailwind)

The published views use Tailwind classes. Make sure your Tailwind content configuration covers the package views (or the published copies):

```
content: [
    // ...
    './vendor/vlados/cascader/src/resources/views/**/*.blade.php',
],
```

Usage
-----

[](#usage)

### Basic usage

[](#basic-usage)

```

```

Use `wire:model.live` (with any modifiers, e.g. `wire:model.live.debounce.500ms`) for live updates. The deprecated `wire-model="category_id"` prop from older versions still works but will be removed in a future release — prefer the standard `wire:model` attribute.

If the bound property already has a value on page load, the component derives the displayed label from the options automatically. You can override it with `selected-text`:

```

```

### Options format

[](#options-format)

The `options` array is two levels deep — parents with an optional `children` array. A parent **with** children is a navigation node and cannot be selected itself; a parent with no children is selectable directly.

```
$categories = [
    [
        'id' => 1,
        'name' => 'Electronics',
        'icon' => 'laptop',      // optional, see Icon Resolver
        'color' => '#3B82F6',    // optional icon color / background tint
        'children' => [
            ['id' => 11, 'name' => 'Phones', 'icon' => 'mobile', 'color' => '#3B82F6'],
            ['id' => 12, 'name' => 'Tablets', 'icon' => 'tablet', 'color' => '#3B82F6'],
        ],
    ],
    [
        'id' => 3,
        'name' => 'Other',  // no children — selectable directly
        'icon' => 'question',
        'color' => '#6B7280',
        'children' => [],
    ],
];
```

> **Values must be unique across the whole tree** — parents and children share one value space. If a parent and a child both had `id: 5`, selection highlighting could not tell them apart.

### Custom value and label fields

[](#custom-value-and-label-fields)

By default the component reads `id` for values and `name` for labels:

```

```

### Clearable selection

[](#clearable-selection)

```

```

### Sizes

[](#sizes)

Two sizes are available, matching Flux UI's select: `sm` (default) and `xs`:

```

```

### Search

[](#search)

The desktop dropdown includes a search box. Results are leaf-only: a query matching a parent lists its children as "Parent / Child" paths, and leaf parents appear directly. Escape clears the search first; pressing Escape again closes the dropdown.

### Mobile customization

[](#mobile-customization)

On screens narrower than 640px the cascader opens as a bottom sheet with Cancel/Confirm buttons:

```

```

### All props

[](#all-props)

PropDefaultDescription`options``[]`The option tree (see format above)`wire:model`—Livewire binding (attribute, supports `.live` and other modifiers)`placeholder``Select...`Trigger text when nothing is selected`selected-text`derivedInitial label override for a pre-selected value`value-field``id`Key used for option values`label-field``name`Key used for option labels`search-placeholder``Search...`Search input placeholder`clearable``false`Show a clear button when a value is selected`cancel-text``Cancel`Mobile sheet cancel button`confirm-text``Confirm`Mobile sheet confirm button`size``sm``sm` or `xs`Icon Resolver
-------------

[](#icon-resolver)

Icons are resolved server-side to HTML through a configurable resolver. The default renders FontAwesome `` tags. Configure a different resolver in `AppServiceProvider::boot()`.

Icon names are validated (letters, numbers, dots, dashes, underscores) and colors are sanitized before rendering — invalid values are rejected or ignored rather than interpolated into markup.

### FontAwesome inline tags (default)

[](#fontawesome-inline-tags-default)

```
use Vlados\Cascader\IconResolver;

IconResolver::useFontAwesome();          // fa-solid (default)
IconResolver::useFontAwesome('regular'); // fa-regular
```

Options use plain icon names: `['icon' => 'laptop']` → ``. Requires FontAwesome CSS on the page.

### Blade FontAwesome components

[](#blade-fontawesome-components)

For projects using [blade-fontawesome](https://github.com/owenvoke/blade-fontawesome):

```
IconResolver::useBladeFontAwesome();      // fas (default)
IconResolver::useBladeFontAwesome('far'); // regular
```

`['icon' => 'laptop']` → ``

### Heroicons

[](#heroicons)

```
IconResolver::useHeroicons();          // solid
IconResolver::useHeroicons('outline'); // outline
```

`['icon' => 'home']` → ``

### Blade Icons (any set)

[](#blade-icons-any-set)

```
IconResolver::useBladeIcons();
```

Pass full component names: `['icon' => 'heroicon-o-home']` → ``

### Custom resolver

[](#custom-resolver)

```
IconResolver::using(function (string $icon, ?string $color = null, string $size = 'sm') {
    return view('components.my-icon', [
        'name' => $icon,
        'color' => $color,
        'size' => $size,
    ])->render();
});
```

The returned HTML is injected with `x-html`, so a custom resolver must escape any untrusted data itself.

### Error handling

[](#error-handling)

If an icon component cannot be rendered, a descriptive `InvalidArgumentException` is thrown:

```
Cascader: Unable to render icon component ''.
Original icon name: 'missing'.
Make sure the icon exists or configure a different IconResolver.

```

Using the Alpine component directly
-----------------------------------

[](#using-the-alpine-component-directly)

If you want your own markup, use the Alpine component without the Blade wrapper:

```

```

`selectedValue` is accepted as a deprecated alias for `modelValue`.

Publishing assets
-----------------

[](#publishing-assets)

```
php artisan vendor:publish --tag=cascader-views    # Blade views
php artisan vendor:publish --tag=cascader-scripts  # Alpine component
```

License
-------

[](#license)

MIT

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance97

Actively maintained with recent releases

Popularity19

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~17 days

Recently: every ~54 days

Total

14

Last Release

16d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/20ebf35eac0da0d3775f3a64bdd9dc0e9dfa11bc9a3c3ee9db92deef9dbf8bd8?d=identicon)[vlados](/maintainers/vlados)

---

Top Contributors

[![vlados](https://avatars.githubusercontent.com/u/46914?v=4)](https://github.com/vlados "vlados (31 commits)")

---

Tags

laravelbladelivewirecomponentdropdownselectalpinejscascader

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/vlados-cascader/health.svg)

```
[![Health](https://phpackages.com/badges/vlados-cascader/health.svg)](https://phpackages.com/packages/vlados-cascader)
```

###  Alternatives

[tallstackui/tallstackui

TallStackUI is a powerful suite of Blade components that elevate your workflow of Livewire applications.

731189.9k16](/packages/tallstackui-tallstackui)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[moonshine/moonshine

Laravel administration panel

1.3k268.2k89](/packages/moonshine-moonshine)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k16.3M154](/packages/laravel-pulse)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9922.4M146](/packages/roots-acorn)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45844.8k1](/packages/pressbooks-pressbooks)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)