Livewire Combobox: A dynamic selects for Laravel Livewire
A Laravel Livewire multiple selects depending on each other values, with infinite levels of dependency and totally configurable.
Requirements
This package need at least:
- PHP ^8.0
- Laravel ^8.0
- Laravel Livewire ^2.0
- TailwindCSS ^2.0
Installation
You can install the package via composer:
composer require daguilarm/livewire-combobox
Add the package styles in the <head> using the helper @LivewireComboboxCss:
<html>
<head>
@LivewireComboboxCss
</head>
<body>
...
</body>
</html>
Documentation
General Methods
The first thing you have to do is create a component in your folder Livewire. Below you can see an example using three selects:
<?php
declare(strict_types=1);
namespace App\Http\Livewire;
use App\Models\Car;
use App\Models\Extra;
use App\Models\Option;
use Daguilarm\LivewireCombobox\Components\ComboboxLivewireComponent;
use Daguilarm\LivewireCombobox\Components\Fields\Select;
use Daguilarm\LivewireCombobox\Contracts\Combobox;
class ComboboxCars extends ComboboxLivewireComponent implements Combobox
{
public function elements(): array
{
return [
Select::make('Cars', Car::class)
->uriKey('key-for-car')
->options(function($model) {
return $model
->pluck('name', 'id')
->toArray();
}),
Select::make('Options for cars', Option::class)
->uriKey('key-for-options')
->dependOn('key-for-car')
->foreignKey('car_id')
->selectRows('id', 'option'),
Select::make('Extras for cars')
->model(Extra::class)
->firstRemoved()
->hideOnEmpty()
->uriKey('key-for-extras')
->dependOn('key-for-options')
->foreignKey('option_id')
->selectRows('id', 'extra')
->withoutResponse(),
];
}
}
The package supports infinite dependent elements. The method elements() should return an array with all the elements.
Let's see how the class works Select::class and its methods:
make()
The method make(), has the following structure:
Select::make(string $label, ?string $model = null);
model()
As it can be seen, the attribute $model is optional in the make() method, and it can be added using the method model():
Select::make('My label')->model(User::class);
⚠️ Defining the model is mandatory, but it can be done in the two ways described.
uriKey()
This method is mandatory, it is used to define a unique key for the element.
hideOnEmpty()
Dependent children are removed if they are empty, instead of showing an empty field.
withoutResponse()
When we want an element does not send a response to the component and works only as a form field, that is, remove all the Laravel Livewire code from it. Very useful when it comes to the last selectable element and we don't want to send a request to the server.
Child elements
These elements have their own methods, apart from those described above. These child elements do not need the method options(), although it can be added if desired. The child specific methods are described below:
dependOn()
With this method we define the parent element on which our child element depends. We must use the uriKey from the parent element. The basic structure of the method is:
dependOn(?string $parentUriKey = null, ?string $foreignKey = null)
As can be seen, it admits a second value which is the foreing key that links the two models: Parent and Child.
foreignKey()
This second field can also be added in two ways:
// Option 1
Select::make(...)
->dependOn('key-for-options', 'option_id');
// Option 2
Select::make(...)
->dependOn('key-for-options')
->foreignKey('option_id');
selectRows()
It is used to select the fields from the table that we want to load in the child element.
disabledOnEmpty()
If you want to disabled the field while it is empty...
Field Types
At the moment, the package support the folowing field types:
Select field
These fields have the following methods:
options()
It is used to add the values that will be shown in the element select. We can directly add an array with the values, or define a callback. The two values returned by the array: key and value, are shown as follows in the Blade template:
// The array
[
1 => 'Car',
2 => 'Bike',
3 => 'Plane'
]
//Will be render as
<option value="1">Car</option>
<option value="2">Bike</option>
<option value="3">Plane</option>
Therefore, in the component example (will be reverse):
// The array
Select::make(...)
->options(function($model) {
return $model
->pluck('name', 'id')
->toArray();
})
//Will be render as
<option value="id">name</option>
firstRemoved()
By default, each item will show a select field with an empty option element:
// Element
<select>
<option value=""></option>
...
</select>
If you want to remove it, you can add the method firstRemoved().
Search field
comming soon...
Loading...
You can activate or deactivate the loading state, modifying the attribute $loading, in your component:
<?php
declare(strict_types=1);
namespace App\Http\Livewire;
use App\Models\Car;
use App\Models\Extra;
use App\Models\Option;
use Daguilarm\LivewireCombobox\Components\ComboboxLivewireComponent;
use Daguilarm\LivewireCombobox\Components\Fields\Select;
use Daguilarm\LivewireCombobox\Contracts\Combobox;
class ComboboxCars extends ComboboxLivewireComponent implements Combobox
{
protected bool $loading = false;
public function elements(): array
{
return [];
}
}
By default it is activated (true). The template file is located at: resources/views/vendor/livewire-combobox/loading.blade.php.
Customize the display of elements
The package uses TailwindCSS so the styles must be based on it. The structure of the elements is as follows:
<!-- Main container -->
<div id="container">
<!-- Element 1 -->
<div id="element-container-1">
<label id="label-1"></label>
<select id="select-1"></select>
</div>
<!-- Element 2 -->
<div id="element-container-2">
<label id="label-2"></label>
<select id="select-2"></select>
</div>
</div>
We can modify the styles of the Main Container from the component that we created at the beginning of the documentation, using the $comboboxContainerClass:
<?php
declare(strict_types=1);
namespace App\Http\Livewire;
use App\Models\Car;
use App\Models\Extra;
use App\Models\Option;
use Daguilarm\LivewireCombobox\Components\ComboboxLivewireComponent;
use Daguilarm\LivewireCombobox\Components\Fields\Select;
use Daguilarm\LivewireCombobox\Contracts\Combobox;
class ComboboxCars extends ComboboxLivewireComponent implements Combobox
{
protected string $containerClass = 'flex p-2 m-2 bg-gray-100';
public function elements(): array
{
return [];
}
}
To modify an element, we will have to do it directly from each of them, using the method class():
Select::make('Cars', Car::class)
->uriKey('key-for-car')
->options(function($model) {
return $model
->pluck('id', 'name')
->toArray();
})
->class('p-4', 'text-green-600', 'text-lg'),
We can use the new functionality of php 8 to modify only those parts that interest us, or we can use the method directly:
// Method 1
Select::make(...)
->class(
container: 'p-4',
field: 'text-lg',
),
// Method 2
Select::make(...)
->class('p-4', null, 'text-lg'),
The order of the parameters is:
class(?string $container = null, ?string $label = null, ?string $field = null)
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.
1 Dec 3, 2021
56 Aug 27, 2022
36 Dec 17, 2022
85 Mar 19, 2022
152 Dec 15, 2022
145 Apr 13, 2022
172 Sep 13, 2022
58 Dec 30, 2022
2 Jun 8, 2022
19 Aug 29, 2022
55 Dec 27, 2022
1.3k Jan 1, 2023
233 Jan 4, 2023
15 Jan 18, 2022
19 Dec 14, 2022
3 Feb 23, 2022
806 Jan 6, 2023