{"id":13423016,"url":"https://github.com/wire-elements/spotlight","last_synced_at":"2025-05-14T18:04:52.328Z","repository":{"id":38398562,"uuid":"355514216","full_name":"wire-elements/spotlight","owner":"wire-elements","description":"Livewire component that brings Spotlight/Alfred-like functionality to your Laravel application.","archived":false,"fork":false,"pushed_at":"2025-02-26T07:12:15.000Z","size":525,"stargazers_count":941,"open_issues_count":8,"forks_count":71,"subscribers_count":16,"default_branch":"2.0","last_synced_at":"2025-05-10T18:07:11.513Z","etag":null,"topics":["laravel","livewire","livewire-components"],"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/wire-elements.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":"PhiloNL"}},"created_at":"2021-04-07T11:09:43.000Z","updated_at":"2025-04-17T08:26:42.000Z","dependencies_parsed_at":"2024-11-16T17:40:21.872Z","dependency_job_id":"7dafab79-f516-41ed-a55d-d910160d25f1","html_url":"https://github.com/wire-elements/spotlight","commit_stats":{"total_commits":51,"total_committers":12,"mean_commits":4.25,"dds":0.4117647058823529,"last_synced_commit":"2bc4fdc5be3ff48d1cf4529b7dd47a60d7d8de45"},"previous_names":["livewire-ui/spotlight"],"tags_count":20,"template":false,"template_full_name":"spatie/package-skeleton-laravel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wire-elements%2Fspotlight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wire-elements%2Fspotlight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wire-elements%2Fspotlight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wire-elements%2Fspotlight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wire-elements","download_url":"https://codeload.github.com/wire-elements/spotlight/tar.gz/refs/heads/2.0","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198514,"owners_count":22030965,"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":["laravel","livewire","livewire-components"],"created_at":"2024-07-30T23:01:05.358Z","updated_at":"2025-05-14T18:04:47.311Z","avatar_url":"https://github.com/wire-elements.png","language":"PHP","funding_links":["https://github.com/sponsors/PhiloNL"],"categories":["UI","Packages / Plugins","PHP"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://user-images.githubusercontent.com/1133950/115727164-a806e700-a383-11eb-8605-9f7b56f987c6.png\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://packagist.org/packages/wire-elements/spotlight\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/wire-elements/spotlight\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/livewire-ui/spotlight\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/livewire-ui/spotlight\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/wire-elements/spotlight\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/wire-elements/spotlight\" alt=\"Latest Stable Version\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/wire-elements/spotlight\"\u003e\u003cimg src=\"https://img.shields.io/packagist/l/wire-elements/spotlight\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## About Wire Elements Spotlight\n\nWire Elements Spotlight is a Livewire component that provides Spotlight/Alfred-like functionality to your Laravel\napplication. \u003ca href=\"https://twitter.com/Philo01/status/1380135839263559680?s=20\"\u003eView demo video\u003c/a\u003e.\n\n## Installation\n\n\u003ca href=\"https://philo.dev/getting-started-with-laravel-spotlight/\"\u003e\u003cimg src=\"https://user-images.githubusercontent.com/1133950/123797901-f76b1580-d8e6-11eb-872a-46d11952ef71.png\" alt=\"Laravel Spotlight Tutorial\"\u003e\u003c/a\u003e\n\nClick the image above to read a full article on using the Wire Elements Spotlight package or follow the instructions below.\n\nTo get started, require the package via Composer:\n\n```shell\ncomposer require wire-elements/spotlight\n```\n\n## Livewire directive\n\nAdd the Livewire directive `@livewire('livewire-ui-spotlight')`:\n\n```html\n\u003chtml\u003e\n\u003cbody\u003e\n\u003c!-- content --\u003e\n\n@livewire('livewire-ui-spotlight')\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Alpine (only when using Livewire v2)\n\nSpotlight requires [Alpine](https://github.com/alpinejs/alpine). You can use the official CDN to quickly include Alpine:\n\n```html\n\u003cscript defer src=\"https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js\"\u003e\u003c/script\u003e\n```\n\n## Opening Spotlight\n\nTo open the Spotlight input bar you can use one of the following shortcuts:\n\n- CTRL + K\n- CMD + K\n- CTRL + /\n- CMD + /\n\nYou can customize the keybindings in the configuration file (see below). It's also possible to toggle Spotlight from any other Livewire component or via Javascript.\n\nIn any Livewire component you can use the `dispatchBrowserEvent` or `dispatch` helper.\n\n```php\n// Livewire v2\n$this-\u003edispatchBrowserEvent('toggle-spotlight');\n\n// Livewire v3\n$this-\u003edispatch('toggle-spotlight');\n```\n\nYou can also use the `$dispatch` helper from Alpine to trigger the same browser event from your markup.\n\n```html\n\u003cbutton @click=\"$dispatch('toggle-spotlight')\"\u003eToggle Spotlight\u003c/button\u003e\n```\n\n## Creating your first Spotlight command\n\nYou can create your first Spotlight command by creating a new class and have it\nextend `LivewireUI\\Spotlight\\SpotlightCommand`. Start by defining a `$name` and `$description` for your command. The\nname and description will be visible when searching through commands.\n\nTo help you get started you can use the `php artisan make:spotlight \u003ccommand-name\u003e` command.\n\n```php\nuse LivewireUI\\Spotlight\\SpotlightCommand;\n\nclass Logout extends SpotlightCommand\n{\n    protected string $name = 'Logout';\n\n    protected string $description = 'Logout out of your account';\n\n}\n```\n\nThe `execute` method is called when a command is chosen, and the command has no dependencies. Let's for example take a\nlook at the `Logout` command `execute` method:\n\n```php\nuse Illuminate\\Contracts\\Auth\\StatefulGuard;\nuse LivewireUI\\Spotlight\\Spotlight;\nuse LivewireUI\\Spotlight\\SpotlightCommand;\n\nclass Logout extends SpotlightCommand\n{\n    protected string $name = 'Logout';\n\n    protected string $description = 'Logout out of your account';\n\n    public function execute(Spotlight $spotlight, StatefulGuard $guard): void\n    {\n        $guard-\u003elogout();\n        $spotlight-\u003eredirect('/');\n    }\n}\n```\n\nAs you can see, you can type-hint your dependencies and have them resolved by Laravel. If you\ntype-hint `Spotlight $spotlight`, you will get access to the Livewire Spotlight component. This gives you access to all\nthe Livewire helpers, so you can redirect users, emit events, you name it.\n\n## How to define search synonyms\n\nSometimes you may want to include additional search terms (often called synonyms) when searching for commands. This can be useful if users refer to something by multiple names or the command may include more than one piece of functionality (for example, a settings page that has multiple types of settings on it). You can add as many synonyms as you want directly on a command by defining a `$synonyms` array:\n\n```php\nuse LivewireUI\\Spotlight\\Spotlight;\nuse LivewireUI\\Spotlight\\SpotlightCommand;\n\nclass ViewBillingSettings extends SpotlightCommand\n{\n    protected string $name = 'View Billing Settings';\n\n    protected string $description = 'Update your billing settings';\n\n    protected array $synonyms = [\n        'subscription',\n        'credit card',\n        'payment',\n    ];\n\n    public function execute(Spotlight $spotlight): void\n    {\n        $spotlight-\u003eredirect('/settings/billing');\n    }\n}\n```\n\nWhen searching, users can now enter \"credit card\" and they'll be shown a search result for the View Billing Settings command.\n\n## How to define command dependencies\n\nIn some cases your command might require dependencies. Let's say we want to create a new user and add it to a specific\nteam. In this case we would need to define a team dependency. To define any dependencies, add a new method to your\ncommand and name the method `dependencies`.\n\nYou can use the `SpotlightCommandDependencies::collection()` method to create a new collection of dependencies. Call\nthe `add` method to register a new dependency. You can add as many of dependencies as you like. The user input prompt\nfollows the order in which you add the commands.\n\n```php\nSpotlightCommandDependencies::collection()\n    -\u003eadd(SpotlightCommandDependency::make('team')-\u003esetPlaceholder('For which team do you want to create a user?'))\n    -\u003eadd(SpotlightCommandDependency::make('foobar')-\u003esetPlaceholder('Input from user')-\u003esetType(SpotlightCommandDependency::INPUT));\n```\n\nFor every dependency, Spotlight will check if a `search{dependency-name}` method exists on the command. This method\nprovides the search query given by the user. For example, to search for our team dependency:\n\n```php\npublic function searchTeam($query)\n{\n    return Team::where('name', 'like', \"%$query%\")\n        -\u003eget()\n        -\u003emap(function(Team $team) {\n            return new SpotlightSearchResult(\n                $team-\u003eid,\n                $team-\u003ename,\n                sprintf('Create license for %s', $team-\u003ename)\n            );\n        });\n}\n```\n\nSpotlight expects a collection of `SpotlightSearchResult` objects. The `SpotlightSearchResult` object consists out of\nthe result identifier, name and description.\n\nEvery dependency will have access to the already defined dependencies. So in the example below, you can see\nthat `searchFoobar` has access to the `Team` the user has chosen. This allows for scoped dependency searching.\n\n```php\nuse LivewireUI\\Spotlight\\Spotlight;\nuse LivewireUI\\Spotlight\\SpotlightCommand;\nuse LivewireUI\\Spotlight\\SpotlightCommandDependencies;\nuse LivewireUI\\Spotlight\\SpotlightCommandDependency;\nuse LivewireUI\\Spotlight\\SpotlightSearchResult;\n\nclass CreateUser extends SpotlightCommand\n{\n    protected string $name = 'Create user';\n\n    protected string $description = 'Create new team user';\n\n    public function dependencies(): ?SpotlightCommandDependencies\n    {\n        return SpotlightCommandDependencies::collection()\n            -\u003eadd(SpotlightCommandDependency::make('team')-\u003esetPlaceholder('For which team do you want to create a user?'))\n            -\u003eadd(SpotlightCommandDependency::make('foobar')-\u003esetPlaceholder('Search for second dependency')\n            );\n    }\n\n    public function searchFoobar($query, Team $team)\n    {\n        // Given Foobar is the second dependency it will have access to any resolved depedencies defined earlier. In this case we can access the Team which was chosen.\n    }\n\n    public function searchTeam($query)\n    {\n        return Team::where('name', 'like', \"%$query%\")\n            -\u003eget()\n            -\u003emap(function(Team $team) {\n                return new SpotlightSearchResult(\n                    $team-\u003eid,\n                    $team-\u003ename,\n                    sprintf('Create user for %s', $team-\u003ename)\n                );\n            });\n    }\n\n    public function execute(Spotlight $spotlight, Team $team, string $name)\n    {\n        $spotlight-\u003eemit('openModal', 'user-create', ['team' =\u003e $team-\u003eid, 'name' =\u003e $name]);\n    }\n}\n```\n\n## Register commands\n\nYou can register commands by adding these to the `livewire-ui-spotlight.php` config file:\n\n```php\n\u003c?php\n\nreturn [\n    'commands' =\u003e [\n        \\App\\SpotlightCommands\\CreateUser::class\n    ]\n];\n```\n\nIt's also possible to register commands via one of your service providers:\n\n```php\nuse \\App\\SpotlightCommands\\CreateUser;\n\nclass AppServiceProvider extends ServiceProvider\n{\n    public function boot()\n    {\n        Spotlight::registerCommand(CreateUser::class);\n\n        // You can also register commands conditionally\n        Spotlight::registerCommandIf(true, CreateUser::class);\n        Spotlight::registerCommandUnless(false, CreateUser::class);\n    }\n\n}\n```\n\nAlternatively, you can also conditionally show or hide a command from the command itself. (Note: you will still need to register your command in your config file or in a service provider.) Add the `shouldBeShown` method to your command and add any logic to resolve if the command should be shown. Dependencies are resolved from the container, so you can for example verify if the currently authenticated user has the required permissions to access given command:\n\n```php\nuse Illuminate\\Http\\Request;\nuse LivewireUI\\Spotlight\\Spotlight;\nuse LivewireUI\\Spotlight\\SpotlightCommand;\n\nclass CreateUser extends SpotlightCommand\n{\n    protected string $name = 'Create user';\n\n    protected string $description = 'Create new team user';\n\n    public function execute(Spotlight $spotlight)\n    {\n        $spotlight-\u003eemit('openModal', 'user-create');\n    }\n\n    public function shouldBeShown(Request $request): bool\n    {\n        return $request-\u003euser()-\u003ecan('create user');\n    }\n}\n```\n\nIf you need to do logic that can't be done in a service provider (for example, any logic that needs to use the currently authenticated user) to determine if your command should be shown in the Spotlight component, you can add a `shouldBeShown` method on your command. You can type-hint any dependencies you need and they'll be resolved out of the container for you. (Note: you will still need to register your command in your config file or in a service provider.)\n\n```php\nuse Illuminate\\Http\\Request;\nuse LivewireUI\\Spotlight\\Spotlight;\nuse LivewireUI\\Spotlight\\SpotlightCommand;\n\nclass CreateUser extends SpotlightCommand\n{\n    protected string $name = 'Create user';\n\n    protected string $description = 'Create new team user';\n\n    public function execute(Spotlight $spotlight)\n    {\n        $spotlight-\u003eemit('openModal', 'user-create');\n    }\n\n    public function shouldBeShown(Request $request): bool\n    {\n        return $request-\u003euser()-\u003ecan('create user');\n    }\n}\n```\n\n\n## Configuration\n\nYou can customize Spotlight via the `livewire-ui-spotlight.php` config file. This includes some additional options like including CSS if you don't use TailwindCSS for your application. To publish the config run the `vendor:publish` command:\n\n```shell\nphp artisan vendor:publish --tag=livewire-ui-spotlight-config\n```\n\n```php\n\u003c?php\n\nreturn [\n\n    /*\n    |--------------------------------------------------------------------------\n    | Shortcuts\n    |--------------------------------------------------------------------------\n    |\n    | Define which shortcuts will activate Spotlight CTRL / CMD + key\n    | The default is CTRL/CMD + K or CTRL/CMD + /\n    |\n    */\n\n    'shortcuts' =\u003e [\n        'k',\n        'slash',\n    ],\n\n    /*\n    |--------------------------------------------------------------------------\n    | Commands\n    |--------------------------------------------------------------------------\n    |\n    | Define which commands you want to make available in Spotlight.\n    | Alternatively, you can also register commands in your AppServiceProvider\n    | with the Spotlight::registerCommand(Logout::class); method.\n    |\n    */\n\n    'commands' =\u003e [\n        \\LivewireUI\\Spotlight\\Commands\\Logout::class\n    ],\n\n    /*\n    |--------------------------------------------------------------------------\n    | Include CSS\n    |--------------------------------------------------------------------------\n    |\n    | Spotlight uses TailwindCSS, if you don't use TailwindCSS you will need\n    | to set this parameter to true. This includes the modern-normalize css.\n    |\n    */\n    'include_css' =\u003e false,\n\n    /*\n    |--------------------------------------------------------------------------\n    | Include JS\n    |--------------------------------------------------------------------------\n    |\n    | Spotlight will inject the required Javascript in your blade template.\n    | If you want to bundle the required Javascript you can set this to false\n    | run `npm install --save fuse.js` and add `require('vendor/wire-elements/spotlight/resources/js/spotlight');`\n    | to your script bundler like webpack.\n    |\n    */\n    'include_js' =\u003e true,\n];\n```\n\nIf you want to translate or change default the placeholder you will need to publish the translation file.\n\n```shell\nphp artisan vendor:publish --tag=livewire-ui-spotlight-translations\n```\n\n```php\n\u003c?php\n\nreturn [\n    'placeholder' =\u003e 'What do you want to do?',\n];\n```\n\nIf you want to change the spotlight view, you can also publish the views.\n\n```shell\nphp artisan vendor:publish --tag=livewire-ui-spotlight-views\n```\n\n## Credits\n\n- [Philo Hermans](https://github.com/philoNL)\n- [All Contributors](../../contributors)\n\n## License\n\nWire Elements is open-sourced software licensed under the [MIT license](LICENSE.md).\n\n## Beautiful components crafted with Livewire\n\n\u003ca href=\"https://wire-elements.dev/pro\"\u003e\u003cimg src=\"https://philo.dev/content/images/size/w1600/2022/07/wire-elements-pro-v2.png\" width=\"600\" alt=\"\" /\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwire-elements%2Fspotlight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwire-elements%2Fspotlight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwire-elements%2Fspotlight/lists"}