About LivewireUI Spotlight
LivewireUI Spotlight is a Livewire component that provides Spotlight/Alfred-like functionality to your Laravel application. View demo video.
Installation
Click the image above to read a full article on using the LivewireUI Spotlight package or follow the instructions below.
To get started, require the package via Composer:
composer require livewire-ui/spotlight
Livewire directive
Add the Livewire directive @livewire('livewire-ui-spotlight'):
<html>
<body>
<!-- content -->
@livewire('livewire-ui-spotlight')
</body>
</html>
Alpine
Spotlight requires Alpine. You can use the official CDN to quickly include Alpine:
<script defer src="https://unpkg.com/[email protected]/dist/cdn.min.js"></script>
Opening Spotlight
To open the Spotlight input bar you can use one of the following shortcuts:
- CTRL + K
- CMD + K
- CTRL + /
- CMD + /
You 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.
In any Livewire component you can use the dispatchBrowserEvent helper.
$this->dispatchBrowserEvent('toggle-spotlight');
You can also use the $dispatch helper from Alpine to trigger the same browser event from your markup.
<button @click="$dispatch('toggle-spotlight')">Toggle Spotlight</button>
Creating your first Spotlight command
You can create your first Spotlight command by creating a new class and have it extend LivewireUI\Spotlight\SpotlightCommand. Start by defining a $name and $description for your command. The name and description will be visible when searching through commands.
To help you get started you can use the php artisan make:spotlight <command-name> command.
<?php
namespace LivewireUI\Spotlight\Commands;
use LivewireUI\Spotlight\SpotlightCommand;
class Logout extends SpotlightCommand
{
protected string $name = 'Logout';
protected string $description = 'Logout out of your account';
}
The execute method is called when a command is chosen, and the command has no dependencies. Let's for example take a look at the Logout command execute method:
<?php
namespace LivewireUI\Spotlight\Commands;
use Illuminate\Contracts\Auth\StatefulGuard;
use LivewireUI\Spotlight\Spotlight;
use LivewireUI\Spotlight\SpotlightCommand;
class Logout extends SpotlightCommand
{
protected string $name = 'Logout';
protected string $description = 'Logout out of your account';
public function execute(Spotlight $spotlight, StatefulGuard $guard): void
{
$guard->logout();
$spotlight->redirect('/');
}
}
As you can see, you can type-hint your dependencies and have them resolved by Laravel. If you type-hint Spotlight $spotlight, you will get access to the Livewire Spotlight component. This gives you access to all the Livewire helpers, so you can redirect users, emit events, you name it.
How to define command dependencies
In some cases your command might require dependencies. Let's say we want to create a new user and add it to a specific team. In this case we would need to define a team dependency. To define any dependencies, add a new method to your command and name the method dependencies.
You can use the SpotlightCommandDependencies::collection() method to create a new collection of dependencies. Call the add method to register a new dependency. You can add as many of dependencies as you like. The user input prompt follows the order in which you add the commands.
SpotlightCommandDependencies::collection()
->add(SpotlightCommandDependency::make('team')->setPlaceholder('For which team do you want to create a user?'))
->add(SpotlightCommandDependency::make('foobar')->setPlaceholder('Input from user')->setType(SpotlightCommandDependency::INPUT));
For every dependency, Spotlight will check if a search{dependency-name} method exists on the command. This method provides the search query given by the user. For example, to search for our team dependency:
public function searchTeam($query)
{
return Team::where('name', 'like', "%$query%")
->get()
->map(function(Team $team) {
return new SpotlightSearchResult(
$team->id,
$team->name,
sprintf('Create license for %s', $team->name)
);
});
}
Spotlight expects a collection of SpotlightSearchResult objects. The SpotlightSearchResult object consists out of the result identifier, name and description.
Every dependency will have access to the already defined dependencies. So in the example below, you can see that searchFoobar has access to the `Team the user has chosen. This allows for scoped dependency searching.
use LivewireUI\Spotlight\Spotlight;
use LivewireUI\Spotlight\SpotlightCommand;
use LivewireUI\Spotlight\SpotlightCommandDependencies;
use LivewireUI\Spotlight\SpotlightCommandDependency;
use LivewireUI\Spotlight\SpotlightSearchResult;
class CreateUser extends SpotlightCommand
{
protected string $name = 'Create user';
protected string $description = 'Create new team user';
public function dependencies(): ?SpotlightCommandDependencies
{
return SpotlightCommandDependencies::collection()
->add(SpotlightCommandDependency::make('team')->setPlaceholder('For which team do you want to create a user?'))
->add(SpotlightCommandDependency::make('name')->setPlaceholder('How do you want to name this user?')->setType(SpotlightCommandDependency::INPUT));
}
public function searchTeam($query)
{
return Team::where('name', 'like', "%$query%")
->get()
->map(function(Team $team) {
return new SpotlightSearchResult(
$team->id,
$team->name,
sprintf('Create user for %s', $team->name)
);
});
}
public function execute(Spotlight $spotlight, Team $team, string $name)
{
$spotlight->emit('openModal', 'user-create', ['team' => $team->id, 'name' => $name]);
}
}
Register commands
You can register commands by adding these to the livewire-ui-spotlight.php config file:
<?php
return [
'commands' => [
\App\SpotlightCommands\CreateUser::class
]
];
It's also possible to register commands via one of your service providers:
use \App\SpotlightCommands\CreateUser;
class AppServiceProvider extends ServiceProvider
{
public function boot()
{
Spotlight::registerCommand(CreateUser::class);
// You can also register commands conditionally
Spotlight::registerCommandIf(true, CreateUser::class);
Spotlight::registerCommandUnless(false, CreateUser::class);
}
}
Alternatively, 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:
use Illuminate\Http\Request;
use LivewireUI\Spotlight\Spotlight;
use LivewireUI\Spotlight\SpotlightCommand;
class CreateUser extends SpotlightCommand
{
protected string $name = 'Create user';
protected string $description = 'Create new team user';
public function execute(Spotlight $spotlight)
{
$spotlight->emit('openModal', 'user-create');
}
public function shouldBeShown(Request $request): bool
{
return $request->user()->can('create user');
}
}
Configuration
You 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:
php artisan vendor:publish --tag=livewire-ui-spotlight-config
<?php
return [
/*
|--------------------------------------------------------------------------
| Shortcuts
|--------------------------------------------------------------------------
|
| Define which shortcuts will activate Spotlight CTRL / CMD + key
| The default is CTRL/CMD + K or CTRL/CMD + /
|
*/
'shortcuts' => [
'k',
'slash',
],
/*
|--------------------------------------------------------------------------
| Commands
|--------------------------------------------------------------------------
|
| Define which commands you want to make available in Spotlight.
| Alternatively, you can also register commands in your AppServiceProvider
| with the Spotlight::registerCommand(Logout::class); method.
|
*/
'commands' => [
\LivewireUI\Spotlight\Commands\Logout::class
],
/*
|--------------------------------------------------------------------------
| Include CSS
|--------------------------------------------------------------------------
|
| Spotlight uses TailwindCSS, if you don't use TailwindCSS you will need
| to set this parameter to true. This includes the modern-normalize css.
|
*/
'include_css' => false,
/*
|--------------------------------------------------------------------------
| Include JS
|--------------------------------------------------------------------------
|
| Spotlight will inject the required Javascript in your blade template.
| If you want to bundle the required Javascript you can set this to false
| and add `require('vendor/livewire-ui/spotlight/resources/js/spotlight');`
| to your script bundler like webpack.
|
*/
'include_js' => true,
];
If you want to translate or change default the placeholder you will need to publish the translation file.
php artisan vendor:publish --tag=livewire-ui-spotlight-translations
<?php
return [
'placeholder' => 'What do you want to do?',
];
Credits
License
Livewire UI is open-sourced software licensed under the MIT license.
![Target [Illuminate\Contracts\Auth\StatefulGuard] is not instantiable.](https://avatars.githubusercontent.com/u/33786190?v=4)
720 Jan 3, 2023
7 Nov 15, 2022
15 Jan 18, 2022
10 Feb 15, 2022
5 Dec 12, 2021
22 Oct 6, 2022
19 Dec 14, 2022
680 Jan 4, 2023
1.3k Jan 1, 2023
233 Jan 4, 2023
87 Oct 13, 2022
806 Jan 6, 2023
20 Aug 11, 2022
32 Sep 6, 2022
67 Nov 21, 2022
88 Dec 23, 2022