{"id":20660588,"url":"https://github.com/daguilarm/livewire-combobox","last_synced_at":"2025-04-19T15:09:10.874Z","repository":{"id":52368170,"uuid":"363116482","full_name":"daguilarm/livewire-combobox","owner":"daguilarm","description":"A laravel Livewire Dynamic Selects with multiple selects depending on each other values, with infinite levels and totally configurable.","archived":false,"fork":false,"pushed_at":"2023-02-11T16:08:12.000Z","size":308,"stargazers_count":25,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-05-20T16:30:01.052Z","etag":null,"topics":["combobox","dynamics","forms","laravel","livewire","multiselect","selects"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daguilarm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["daguilarm"]}},"created_at":"2021-04-30T11:15:17.000Z","updated_at":"2024-02-29T21:11:26.000Z","dependencies_parsed_at":"2022-08-21T05:40:23.802Z","dependency_job_id":null,"html_url":"https://github.com/daguilarm/livewire-combobox","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daguilarm%2Flivewire-combobox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daguilarm%2Flivewire-combobox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daguilarm%2Flivewire-combobox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daguilarm%2Flivewire-combobox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daguilarm","download_url":"https://codeload.github.com/daguilarm/livewire-combobox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224951289,"owners_count":17397387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["combobox","dynamics","forms","laravel","livewire","multiselect","selects"],"created_at":"2024-11-16T19:04:14.862Z","updated_at":"2024-11-16T19:04:15.582Z","avatar_url":"https://github.com/daguilarm.png","language":"PHP","funding_links":["https://github.com/sponsors/daguilarm"],"categories":[],"sub_categories":[],"readme":"![Package Logo](https://banners.beyondco.de/A%20Combobox%20for%20Laravel%20Livewire.png?theme=light\u0026packageManager=composer+require\u0026packageName=daguilarm%2Flivewire-combobox\u0026pattern=architect\u0026style=style_1\u0026description=An+infinite+dynamic+selects.\u0026md=1\u0026showWatermark=1\u0026fontSize=100px\u0026images=selector)\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/daguilarm/livewire-combobox.svg?style=flat-square)](https://packagist.org/packages/daguilarm/livewire-combobox)\n[![StyleCI](https://styleci.io/repos/363116482/shield?style=plastic)](https://github.styleci.io/repos/363116482)\n![GitHub last commit](https://img.shields.io/github/last-commit/daguilarm/livewire-combobox)\n\u003c!-- [![Total Downloads](https://img.shields.io/packagist/dt/daguilarm/livewire-combobox.svg?style=flat-square)](https://packagist.org/packages/daguilarm/livewire-combobox) --\u003e\n\n# Livewire Combobox: A dynamic selects for Laravel Livewire\n\nA Laravel Livewire multiple selects depending on each other values, with infinite levels of dependency and totally configurable.\n\n## Requirements\n\nThis package need at least:\n\n- PHP ^8.0\n- Laravel ^8.0\n- Laravel Livewire ^2.0\n- TailwindCSS ^2.0\n\n## Installation\n\nYou can install the package via composer:\n\n    composer require daguilarm/livewire-combobox\n\nAdd the package styles in the `\u003chead\u003e` using the helper `@LivewireComboboxCss`:\n\n```html \n\u003chtml\u003e\n    \u003chead\u003e\n        @LivewireComboboxCss\n    \u003c/head\u003e\n    \u003cbody\u003e\n        ...\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n# Documentation\n\n## General Methods\n\nThe first thing you have to do is create a component in your folder **Livewire**. Below you can see an example using three selects:\n\n```php \n\u003c?php\n\ndeclare(strict_types=1);\n\nnamespace App\\Http\\Livewire;\n\nuse App\\Models\\Car;\nuse App\\Models\\Extra;\nuse App\\Models\\Option;\nuse Daguilarm\\LivewireCombobox\\Components\\ComboboxLivewireComponent;\nuse Daguilarm\\LivewireCombobox\\Components\\Fields\\Select;\nuse Daguilarm\\LivewireCombobox\\Contracts\\Combobox;\n\nclass ComboboxCars extends ComboboxLivewireComponent implements Combobox\n{\n    public function elements(): array\n    {\n        return [\n            Select::make('Cars', Car::class)\n                -\u003euriKey('key-for-car')\n                -\u003eoptions(function($model) {\n                    return $model\n                        -\u003epluck('name', 'id')\n                        -\u003etoArray();\n                }),\n            Select::make('Options for cars', Option::class)\n                -\u003euriKey('key-for-options')\n                -\u003edependOn('key-for-car')\n                -\u003eforeignKey('car_id')\n                -\u003eselectRows('id', 'option'),\n            Select::make('Extras for cars')\n                -\u003emodel(Extra::class)\n                -\u003efirstRemoved()\n                -\u003ehideOnEmpty()\n                -\u003euriKey('key-for-extras')\n                -\u003edependOn('key-for-options')\n                -\u003eforeignKey('option_id')\n                -\u003eselectRows('id', 'extra')\n                -\u003ewithoutResponse(),\n        ];\n    }\n}\n```\n\nThe **package** supports infinite dependent elements. The method `elements()` should return an array with all the elements. \n\nLet's see how the class works `Select::class` and its methods:\n\n#### make()\n\nThe method `make()`, has the following structure:\n\n```php\nSelect::make(string $label, ?string $model = null);\n```\n\n#### model()\n\nAs it can be seen, the attribute `$model` is optional in the `make()` method, and it can be added using the method `model()`:\n\n```php\nSelect::make('My label')-\u003emodel(User::class);\n```\n\n\u003e :warning: Defining the model is mandatory, but it can be done in the two ways described.\n\n#### uriKey()\n\nThis method is mandatory, it is used to define a unique key for the element.\n\n#### hideOnEmpty()\n\nDependent children are removed if they are empty, instead of showing an empty field.\n\n#### withoutResponse()\n\nWhen 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.\n\n## Child elements\n\nThese elements have their own methods, apart from those described above. \nThese child elements do not need the method `options()`, although it can be added if desired. The child specific methods are described below:\n\n### dependOn()\n\nWith 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:\n\n```php\ndependOn(?string $parentUriKey = null, ?string $foreignKey = null)\n```\n\nAs can be seen, it admits a second value which is the *foreing key* that links the two models: **Parent** and **Child**. \n\n### foreignKey()\n\nThis second field can also be added in two ways:\n\n```php \n// Option 1\nSelect::make(...)\n    -\u003edependOn('key-for-options', 'option_id');\n\n// Option 2\nSelect::make(...)\n    -\u003edependOn('key-for-options')\n    -\u003eforeignKey('option_id');\n```\n\n### selectRows()\n\nIt is used to select the fields from the table that we want to load in the child element.\n\n#### disabledOnEmpty()\n\nIf you want to disabled the field while it is empty...\n\n## Field Types \n\nAt the moment, the package support the folowing field types:\n\n### Select field\n\nThese fields have the following methods:\n\n#### options()\n\nIt 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:\n\n```php \n// The array\n[\n    1 =\u003e 'Car',\n    2 =\u003e 'Bike',\n    3 =\u003e 'Plane'\n]\n\n//Will be render as \n\u003coption value=\"1\"\u003eCar\u003c/option\u003e\n\u003coption value=\"2\"\u003eBike\u003c/option\u003e\n\u003coption value=\"3\"\u003ePlane\u003c/option\u003e\n```\n\nTherefore, in the component example (will be reverse):\n\n```php \n// The array\nSelect::make(...)\n    -\u003eoptions(function($model) {\n        return $model\n            -\u003epluck('name', 'id')\n            -\u003etoArray();\n    })\n\n//Will be render as \n\u003coption value=\"id\"\u003ename\u003c/option\u003e\n```\n\n#### firstRemoved()\n\nBy default, each item will show a select field with an empty `option` element:\n\n```html \n// Element\n\u003cselect\u003e\n    \u003coption value=\"\"\u003e\u003c/option\u003e\n    ...\n\u003c/select\u003e\n```\n\nIf you want to remove it, you can add the method `firstRemoved()`.\n\n### Search field \n\ncomming soon... \n\n## Loading... \n\nYou can activate or deactivate the loading state, modifying the attribute `$loading`, in your component:\n\n```php \n\u003c?php\n\ndeclare(strict_types=1);\n\nnamespace App\\Http\\Livewire;\n\nuse App\\Models\\Car;\nuse App\\Models\\Extra;\nuse App\\Models\\Option;\nuse Daguilarm\\LivewireCombobox\\Components\\ComboboxLivewireComponent;\nuse Daguilarm\\LivewireCombobox\\Components\\Fields\\Select;\nuse Daguilarm\\LivewireCombobox\\Contracts\\Combobox;\n\nclass ComboboxCars extends ComboboxLivewireComponent implements Combobox\n{\n    protected bool $loading = false;\n\n    public function elements(): array\n    {\n        return [];\n    }\n}\n```\n\nBy default it is activated (true). The template file is located at: `resources/views/vendor/livewire-combobox/loading.blade.php`.\n\n## Customize the display of elements\n\nThe package uses **TailwindCSS** so the styles must be based on it. The structure of the elements is as follows:\n\n```html \n\u003c!-- Main container --\u003e\n\u003cdiv id=\"container\"\u003e\n\n    \u003c!-- Element 1 --\u003e\n    \u003cdiv id=\"element-container-1\"\u003e\n        \u003clabel id=\"label-1\"\u003e\u003c/label\u003e\n        \u003cselect id=\"select-1\"\u003e\u003c/select\u003e\n    \u003c/div\u003e\n\n    \u003c!-- Element 2 --\u003e\n    \u003cdiv id=\"element-container-2\"\u003e\n        \u003clabel id=\"label-2\"\u003e\u003c/label\u003e\n        \u003cselect id=\"select-2\"\u003e\u003c/select\u003e\n    \u003c/div\u003e\n\n\u003c/div\u003e\n```\n\nWe can modify the styles of the *Main Container* from the component that we created at the beginning of the documentation, using the `$comboboxContainerClass`:\n\n```php \n\u003c?php\n\ndeclare(strict_types=1);\n\nnamespace App\\Http\\Livewire;\n\nuse App\\Models\\Car;\nuse App\\Models\\Extra;\nuse App\\Models\\Option;\nuse Daguilarm\\LivewireCombobox\\Components\\ComboboxLivewireComponent;\nuse Daguilarm\\LivewireCombobox\\Components\\Fields\\Select;\nuse Daguilarm\\LivewireCombobox\\Contracts\\Combobox;\n\nclass ComboboxCars extends ComboboxLivewireComponent implements Combobox\n{\n    protected string $containerClass = 'flex p-2 m-2 bg-gray-100';\n\n    public function elements(): array\n    {\n        return [];\n    }\n}\n```\n\nTo modify an element, we will have to do it directly from each of them, using the method `class()`:\n\n```php \nSelect::make('Cars', Car::class)\n    -\u003euriKey('key-for-car')\n    -\u003eoptions(function($model) {\n        return $model\n            -\u003epluck('id', 'name')\n            -\u003etoArray();\n    })\n    -\u003eclass('p-4', 'text-green-600', 'text-lg'),\n```\n\nWe can use the new functionality of **php 8** to modify only those parts that interest us, or we can use the method directly:\n\n```php \n// Method 1\nSelect::make(...)\n    -\u003eclass(\n        container: 'p-4',\n        field: 'text-lg',\n    ),\n\n// Method 2\nSelect::make(...)\n    -\u003eclass('p-4', null, 'text-lg'),\n```\n\nThe order of the parameters is:\n\n```php \nclass(?string $container = null, ?string $label = null, ?string $field = null)\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n### Security\n\nIf you discover any security related issues, please email damian.aguilarm@gmail.com instead of using the issue tracker.\n\n## Credits\n\n- [Damián Aguilar](https://github.com/daguilarm)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaguilarm%2Flivewire-combobox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaguilarm%2Flivewire-combobox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaguilarm%2Flivewire-combobox/lists"}