{"id":15450381,"url":"https://github.com/kirschbaum-development/livewire-filters","last_synced_at":"2025-04-19T22:58:22.331Z","repository":{"id":41874149,"uuid":"462767384","full_name":"kirschbaum-development/livewire-filters","owner":"kirschbaum-development","description":"Livewire Filters is a series of Livewire components that provide you with the tools to do live filtering of your data from your own Livewire components.","archived":false,"fork":false,"pushed_at":"2023-10-09T10:15:02.000Z","size":76,"stargazers_count":15,"open_issues_count":3,"forks_count":0,"subscribers_count":13,"default_branch":"dev","last_synced_at":"2025-03-29T13:51:17.102Z","etag":null,"topics":["filtering","laravel","livewire"],"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/kirschbaum-development.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"kirschbaum-development"}},"created_at":"2022-02-23T14:23:00.000Z","updated_at":"2024-09-09T01:13:35.000Z","dependencies_parsed_at":"2024-11-16T17:39:35.824Z","dependency_job_id":"a7ea904e-9d7b-49c0-991a-3f250dec762b","html_url":"https://github.com/kirschbaum-development/livewire-filters","commit_stats":{"total_commits":44,"total_committers":5,"mean_commits":8.8,"dds":"0.36363636363636365","last_synced_commit":"91eff722ce77e9ff95bcb0c3c0173a5218bf5855"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":"spatie/package-skeleton-laravel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kirschbaum-development%2Flivewire-filters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kirschbaum-development%2Flivewire-filters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kirschbaum-development%2Flivewire-filters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kirschbaum-development%2Flivewire-filters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kirschbaum-development","download_url":"https://codeload.github.com/kirschbaum-development/livewire-filters/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249826664,"owners_count":21330673,"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":["filtering","laravel","livewire"],"created_at":"2024-10-01T21:04:58.632Z","updated_at":"2025-04-19T22:58:22.298Z","avatar_url":"https://github.com/kirschbaum-development.png","language":"PHP","funding_links":["https://github.com/sponsors/kirschbaum-development"],"categories":[],"sub_categories":[],"readme":"[//]: # (![Mail Intercept banner]\u0026#40;screenshots/banner.jpg\u0026#41;)\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/kirschbaum-development/livewire-filters)](https://packagist.org/packages/kirschbaum-development/livewire-filters)\n[![Total Downloads](https://img.shields.io/packagist/dt/kirschbaum-development/livewire-filters)](https://packagist.org/packages/kirschbaum-development/livewire-filters)\n[![Actions Status](https://github.com/kirschbaum-development/livewire-filters/workflows/run-tests/badge.svg)](https://github.com/kirschbaum-development/livewire-filters/actions)\n\nLivewire Filters is a series of Livewire components that provide you with the tools to do live filtering of your data from your own Livewire components.\n\n## Requirements\n\nThis package requires Laravel 9.0+ and Livewire 2.10+.\n\n## Installation\n\nTo get started, require the package via Composer:\n\n```bash\ncomposer require kirschbaum-development/livewire-filters\n```\n\n### Publishing views\n\nThe included filters are made with [Tailwind CSS](https://tailwindcss.com) and the [Tailwind CSS Forms plugin](https://github.com/tailwindlabs/tailwindcss-forms). We recommend publishing the views and changing the markup to match whatever styling or CSS framework your project uses.\n\n```bash\nphp artisan vendor:publish --tag=livewire-filters-views\n```\n\n### Publishing config\n\nPublishing the config file is only necessary to enable query string usage.\n```bash\nphp artisan vendor:publish --tag=livewire-filters-config\n```\n\n## Usage\n\n### Define your filters\n\nYou can use filters in your Livewire component by including the `HasFilters` trait provided by the package.\n\nWith the trait included, define a `filters` method that returns an array of `Filter` objects you want to use in your component. The included `Filter` class has a series of fluent methods for building up the specifics of each of your filters.\n\n```php\nuse HasFilters;\n\npublic function filters(): array\n{\n    return [\n        Filter::make('title'),\n        Filter::make('type')-\u003eoptions(['text', 'link', 'audio', 'video'])-\u003edefault(['audio']),\n        Filter::make('status')-\u003eoptions(['published', 'draft'])-\u003edefault('published'),\n    ];\n}\n```\n\n### Use your filters\n\nWith your component setup, you can include filters in the view file of your Livewire component. In order to setup the filter, simply use one of the filter components and pass the specific filter by its key. The component will take care of setting itself up.\n\n```blade\n\u003clivewire:livewire-filters-checkbox :filter=\"$filters['type']\" /\u003e\n```\n\nThere is more information below about the included filters in the package.\n\n### Determining filtered status/count\n\nThe `HasFilters` trait includes two computed properties you can use to determine if there are active filters and how many of your filters are currently active. You can access these directly in your Livewire component by using `$this-\u003eisFiltered` or `$this-\u003eactiveFilterCount`. You can also pass one or both of these properties to your Livewire component through the `render` method if you so choose.\n\nThese computed properties are handy if you want to change the color of a button, show/hide a specific section of your UI, show a badge of active filters, or simply show a visual indicator that there are active filters being applied.\n\n### Getting filtered values\n\nBecause the `$filters` array contains `Filter` objects, you will need to either access the `value` property, use the `value()` method, or use the included `getFilterValue($key)` helper method.\n\n```php\n// Helper included in the HasFilters trait\n$this-\u003egetFilteredValue('type');\n\n// Using the accessor\n$this-\u003efilters['type']-\u003evalue();\n\n// Using the property directly\n$this-\u003efilters['type']-\u003evalue;\n```\n\n### Example parent component\n\n```php\nuse App\\Models\\Post;\nuse Kirschbaum\\LivewireFilters\\Filter;\nuse Kirschbaum\\LivewireFilters\\HasFilters;\nuse Livewire\\Component;\n\nclass PostsList extends Component\n{\n    use HasFilters;\n\n    public function filters(): array\n    {\n        return [\n            Filter::make('type')-\u003eoptions(['text', 'link', 'audio', 'video'])-\u003edefault(['text', 'link']),\n        ];\n    }\n\n    public function getPostsProperty()\n    {\n        return Post::query()\n            -\u003ewhen($this-\u003egetFilterValue('type'), fn ($query, $values) =\u003e $query-\u003ewhereIn('type', $values))\n            -\u003epaginate();\n    }\n\n    public function render()\n    {\n        return view('livewire.posts-list', [\n            'filterCount' =\u003e $this-\u003efilterCount,\n            'isFiltered' =\u003e $this-\u003eisFiltered,\n            'posts' =\u003e $this-\u003eposts,\n        ]);\n    }\n}\n```\n\n## Included filters\n\nThe package includes 4 basic filters that can be used in your Livewire components.\n\n### Checkbox filter\n\nThe checkbox filter allows you to select any number of options. Every time a change is made, the filter will emit an event with an array of the currently checked values.\n\n```blade\n\u003clivewire:livewire-filters-checkbox :filter=\"$filters['type']\" /\u003e\n```\n\n| Setting | Type     | Example           |\n|---------|----------|-------------------|\n| key     | `string` | `'type'`          |\n| options | `array`  | `['a', 'b', 'c']` |\n| default | `array`  | `['a', 'b']`      |\n| value   | `array`  | `['b', 'c']`      |\n\n### Radio button filter\n\nThe radio button filter allows you to select a single option from the list of options. Every time a change is made, the filter will emit an event with the currently checked value.\n\n```blade\n\u003clivewire:livewire-filters-radio :filter=\"$filters['type']\" /\u003e\n```\n\n| Setting | Type     | Example           |\n|---------|----------|-------------------|\n| key     | `string` | `'type'`          |\n| options | `array`  | `['a', 'b', 'c']` |\n| default | `string` | `'a'`             |\n| value   | `string` | `'b'`             |\n\n### Select menu filter\n\nSimilar to the radio button filter, the select menu filter allows you to select a single option from the list of options from a select menu. Every time a change is made, the filter will emit an event with the currently selected value.\n\n```blade\n\u003clivewire:livewire-filters-select :filter=\"$filters['type']\" /\u003e\n```\n\n| Setting | Type     | Example           |\n|---------|----------|-------------------|\n| key     | `string` | `'type'`          |\n| options | `array`  | `['a', 'b', 'c']` |\n| default | `string` | `'a'`             |\n| value   | `string` | `'b'`             |\n\n### Text box filter\n\nThe text box filter allows you to type freeform text that you can use for filtering. Every time a change is made, the filter will emit an event with the value of the text field.\n\n```blade\n\u003clivewire:livewire-filters-text :filter=\"$filters['type']\" /\u003e\n```\n\n| Setting | Type     | Example  |\n|---------|----------|----------|\n| key     | `string` | `'name'` |\n| default | `string` | `'John'` |\n| value   | `string` | `'Jane'` |\n\n## The `Filter` class\n\nThe `Filter` class provides a fluent interface for defining filters in your Livewire component as well as retrieving information about the filter.\n\n### `make($key)`\n\nThe first method you must call is the `make` method and pass it a unique key. After this method has been called, you can call any of the other methods in whatever order you want.\n\n### `options($values)`\n\nIf you're using a filter that requires options, you can pass an array of those values into the `options` method. Calling the `options` method without any arguments will return the defined options for the filter.\n\n### `value($values)`\n\nIf you would like to set the value of a filter, you can pass the value or an array of values into the `value` method. Calling the `value` method without any arguments will return the current value of the filter.\n\n### `default($values)`\n\nWhen defining a filter, you should use the `default` method to set the initial value of the filter. This will store the initial value on the object as well to help with determining the status of active filters as well as resetting the filter to its original state. Calling the `default` method without any arguments will return the initial value that you specified when you defined the filter.\n\n### `meta(array $values)`\n\nIf you would like to set additional information on the filter to be used in the view file, you can pass an array of values into the `meta` method. Calling the `meta` method without any arguments will return the current array of meta information.\n\n## Events\n\n### `livewire-filters-reset`\n\n### `livewire-filters-updated`\n\nWhen a filter is updated, it will emit this event with 2 arguments: `key` and `payload`. The key should be used in identifying which filter should be updated. The `payload` is the new value of the filter.\n\nThis event is automatically handled by the `HasFilters` trait. If you would like to customize how the updates are handled, you can listen for this event and use your own method or override the `handleUpdateEvent` method.\n\n## Making your own filters\n\nIn addition to the included filters, you can also make additional filters to suit your needs.\n\n```php\nuse Kirschbaum\\LivewireFilters\\FilterComponent;\n\nclass DateFilter extends FilterComponent\n{\n    public function render()\n    {\n        return view('livewire.filters.date-filter');\n    }\n}\n```\n\n```blade\n\u003cdiv\n    x-data\n    x-init=\"window.flatpickr($refs.flatpickr)\"\n\u003e\n    \u003cinput\n        type=\"text\"\n        name=\"{{ $key }}\"\n        id=\"{{ $key }}\"\n        class=\"focus:ring-indigo-500 focus:border-indigo-500 block w-full pr-8 sm:text-sm border-gray-300 rounded-md\"\n        placeholder=\"Select a date...\"\n        readonly=\"readonly\"\n        x-ref=\"flatpickr\"\n        wire:model=\"value\"\n    \u003e\n\n    @if ($value !== $initialValue)\n        \u003cdiv class=\"absolute inset-y-0 right-2 flex items-center\"\u003e\n            \u003cbutton type=\"button\" class=\"text-gray-400 hover:text-gray-500\" wire:click=\"resetValue\"\u003e\n                \u003csvg xmlns=\"http://www.w3.org/2000/svg\" class=\"h-5 w-5\" viewBox=\"0 0 20 20\" fill=\"currentColor\"\u003e\u003cpath fill-rule=\"evenodd\" d=\"M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z\" clip-rule=\"evenodd\" /\u003e\u003c/svg\u003e\n                \u003cspan class=\"sr-only\"\u003eReset\u003c/span\u003e\n            \u003c/button\u003e\n        \u003c/div\u003e\n    @endif\n\u003c/div\u003e\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on 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 david@kirschbaumdevelopment.com or nathan@kirschbaumdevelopment.com instead of using the issue tracker.\n\n## Credits\n\n- [David VanScott](https://github.com/davidvanscott)\n\n## Sponsorship\n\nDevelopment of this package is sponsored by Kirschbaum, a developer driven company focused on problem solving, team building, and community. Learn more [about us](https://kirschbaumdevelopment.com) or [join us](https://careers.kirschbaumdevelopment.com)!\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%2Fkirschbaum-development%2Flivewire-filters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkirschbaum-development%2Flivewire-filters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkirschbaum-development%2Flivewire-filters/lists"}