PHPackages                             cswni/spotlight - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Admin Panels](/categories/admin)
4. /
5. cswni/spotlight

ActiveLibrary[Admin Panels](/categories/admin)

cswni/spotlight
===============

Livewire component that provides Spotlight/Alfred-like functionality to your Laravel application.

1.0.0(2y ago)0891MITPHPPHP ^8.0

Since Jul 30Pushed 2y agoCompare

[ Source](https://github.com/cswni/spotlight)[ Packagist](https://packagist.org/packages/cswni/spotlight)[ Docs](https://github.com/livewire-ui/spotlight)[ GitHub Sponsors](https://github.com/livewire-ui)[ RSS](/packages/cswni-spotlight/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (8)Versions (2)Used By (1)

 [![](https://user-images.githubusercontent.com/1133950/115727164-a806e700-a383-11eb-8605-9f7b56f987c6.png)](https://user-images.githubusercontent.com/1133950/115727164-a806e700-a383-11eb-8605-9f7b56f987c6.png)

[![Total Downloads](https://camo.githubusercontent.com/84b4da032a6f0337d20ba806977025458e9b7eb14a521df8733b00bd25ae62b0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f776972652d656c656d656e74732f73706f746c69676874)](https://packagist.org/packages/wire-elements/spotlight)[![Total Downloads](https://camo.githubusercontent.com/62f03a067e16f54528b28ad679a95608ed79243e902191a4cf3b430f4c7cf5b1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c697665776972652d75692f73706f746c69676874)](https://packagist.org/packages/livewire-ui/spotlight)[![Latest Stable Version](https://camo.githubusercontent.com/edcbe0ccbee5b6795035d02322a6d07acd1c3f16d0f5fd88c824522f928847fc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f776972652d656c656d656e74732f73706f746c69676874)](https://packagist.org/packages/wire-elements/spotlight)[![License](https://camo.githubusercontent.com/8f0127c701bfb9049385e647519dfc6bb792d7278559c659eeb7126b09ee8ee5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f776972652d656c656d656e74732f73706f746c69676874)](https://packagist.org/packages/wire-elements/spotlight)

About Wire Elements Spotlight
-----------------------------

[](#about-wire-elements-spotlight)

Wire Elements Spotlight is a Livewire component that provides Spotlight/Alfred-like functionality to your Laravel application. [View demo video](https://twitter.com/Philo01/status/1380135839263559680?s=20).

Installation
------------

[](#installation)

[![Laravel Spotlight Tutorial](https://user-images.githubusercontent.com/1133950/123797901-f76b1580-d8e6-11eb-872a-46d11952ef71.png)](https://philo.dev/getting-started-with-laravel-spotlight/)

Click the image above to read a full article on using the Wire Elements Spotlight package or follow the instructions below.

To get started, require the package via Composer:

```
composer require wire-elements/spotlight
```

Livewire directive
------------------

[](#livewire-directive)

Add the Livewire directive `@livewire('livewire-ui-spotlight')`:

```

@livewire('livewire-ui-spotlight')

```

Alpine
------

[](#alpine)

Spotlight requires [Alpine](https://github.com/alpinejs/alpine). You can use the official CDN to quickly include Alpine:

```

```

Opening Spotlight
-----------------

[](#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.

```
Toggle Spotlight
```

Creating your first Spotlight command
-------------------------------------

[](#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.

```
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:

```
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 search synonyms
-----------------------------

[](#how-to-define-search-synonyms)

Sometimes 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:

```
use LivewireUI\Spotlight\Spotlight;
use LivewireUI\Spotlight\SpotlightCommand;

class ViewBillingSettings extends SpotlightCommand
{
    protected string $name = 'View Billing Settings';

    protected string $description = 'Update your billing settings';

    protected array $synonyms = [
        'subscription',
        'credit card',
        'payment',
    ];

    public function execute(Spotlight $spotlight): void
    {
        $spotlight->redirect('/settings/billing');
    }
}
```

When searching, users can now enter "credit card" and they'll be shown a search result for the View Billing Settings command.

How to define command dependencies
----------------------------------

[](#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('foobar')->setPlaceholder('Search for second dependency')
            );
    }

    public function searchFoobar($query, Team $team)
    {
        // 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.
    }

    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
-----------------

[](#register-commands)

You can register commands by adding these to the `livewire-ui-spotlight.php` config file:

```