Wire Extender

https://wire-elements.dev/
Admin
Wire Extender enables embedding Livewire components into any website or static HTML file, allowing...
Tokens:17,020
Snippets:120
Trust Score:6.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Wire Elements Pro via Composer

Source: https://wire-elements.dev/index

After configuring the repository in `composer.json`, run this command to install the Wire Elements Pro package. You will be prompted for your Unlock email (username) and license key (password).

```bash
composer require wire-elements/pro
```

--------------------------------

### Configure Composer Repository for Wire Elements Pro

Source: https://wire-elements.dev/getting-started/installation

To install the private Wire Elements Pro package, you must add its Composer repository to your project's `composer.json` file. This configuration points Composer to the correct URL to fetch the package, which is distributed via a private repository on Unlock.

```json
{
  "repositories": [
    {
      "type": "composer",
      "url": "https://wire-elements-pro.composer.sh"
    }
  ]
}
```

--------------------------------

### Configure Composer Repository for Wire Elements Pro

Source: https://wire-elements.dev/index

To install Wire Elements Pro, you must add its private package repository to your project's `composer.json` file. This allows Composer to locate and download the package from the Unlock private repository.

```json
{
  "repositories": [
    {
      "type": "composer",
      "url": "https://wire-elements-pro.composer.sh"
    }
  ]
}
```

--------------------------------

### Publish Package Assets

Source: https://wire-elements.dev/getting-started/insert-component

As an alternative to compiling assets, you can publish the pre-built CSS and JavaScript files directly to your public directory using this Artisan command. This is required if you are using the Bootstrap preset.

```bash
php artisan vendor:publish --tag=wire-elements-pro-assets

Copied Directory [/wire-elements-pro/resources/dist] To [/public/vendor/wire-elements-pro]
Publishing complete.
```

--------------------------------

### Set Bootstrap as the Front-End Framework

Source: https://wire-elements.dev/getting-started/insert-component

If you are using Bootstrap as your front-end framework, you must change the `default` preset in the published `config/wire-elements-pro.php` file from 'tailwind' to 'bootstrap'.

```php
return [
    'default' => 'bootstrap',

    // ...
];
```

--------------------------------

### Create a Custom Spotlight Action Class

Source: https://wire-elements.dev/getting-started/spotlight-component

You can create custom actions by extending the `SpotlightAction` class. This example defines a `JumpTo` action that takes a path, provides a description, and implements the `execute` method to redirect the user via the Spotlight component.

```php
class JumpTo extends SpotlightAction
{
    public string $path;

    public string $description;

    public function __construct(string $path, string $description = 'Jump to')
    {
        $this->path = $path;
        $this->description = $description;
    }

    public function description(): string
    {
        return $this->description;
    }

    public function execute(Spotlight $spotlight)
    {
        $spotlight->redirect($this->path);
    }
}
```

--------------------------------

### Define a Basic Livewire Modal Component

Source: https://wire-elements.dev/getting-started/modal-component

Create a Livewire modal component by extending `WireElements\Pro\Components\Modal\Modal`. This example shows the basic structure with empty `behavior()` and `attributes()` static methods, which can be implemented to override default configurations.

```php
namespace App\Http\Livewire;

use WireElements\Pro\Components\Modal\Modal;

class UsersOverview extends Modal
{
    public function render()
    {
        return view('livewire.users-overview');
    }

    public static function behavior(): array
    {
        return [];
    }

    public static function attributes(): array
    {
        return [];
    }
}
```

--------------------------------

### Publish the Configuration File

Source: https://wire-elements.dev/getting-started/insert-component

Run this Artisan command to publish the Wire Elements Pro configuration file. This action copies the default configuration to your application's `config` directory, enabling you to customize default behaviors and attributes.

```bash
php artisan vendor:publish --tag=wire-elements-pro-config
```

--------------------------------

### Configure Spotlight Icon Mapping

Source: https://wire-elements.dev/getting-started/spotlight-component

This PHP configuration snippet demonstrates how to map string aliases to their corresponding icon classes. This example shows the mapping for Heroicons, which are included by default.

```php
'academic-cap' => WireElements\Pro\Icons\AcademicCap::class,
'adjustments-horizontal' => WireElements\Pro\Icons\AdjustmentsHorizontal::class,
```

--------------------------------

### Advanced Confirmation Modal Customization and API Reference

Source: https://wire-elements.dev/getting-started/modal-component

The `askForConfirmation` method accepts an array of options to customize its appearance and behavior. The example below demonstrates available parameters like `prompt`, `tableData`, and `confirmPhrase`, followed by a reference for all available options.

```php
$this->askForConfirmation(
    callback: function() use ($userId) {
        User::find($userId)?->delete();
    },
    prompt: [
        'title' => __('Warning! Destructive action'),
        'message' => __('Are you sure you want to delete this user?'),
        'confirm' => __('Yes, Delete'),
        'cancel' => __('Stop'),
    ],
    tableHeaders: ['Column 1', 'Column 2'],
    tableData: [
        ['Row 1 - Column 1 Value', 'Row 1 - Column 2 value'],
        ['Row 2 - Column 1 Value', 'Row 2 - Column 2 value'],
    ],
    confirmPhrase: 'DELETE',
    theme: 'warning',
    metaData: [
        'custom' => 'meta data'
    ],
    modalBehavior: [
        'close-on-escape' => false,
        'close-on-backdrop-click' => false,
        'trap-focus' => true,
    ],
    modalAttributes: [
        'size' => '2xl'
    ]
);
```

```APIDOC
prompt: (array)
  Override the default confirmation prompt with your own copy.

tableHeaders: (array)
  Create a table and set the column headers.

tableData: (array)
  Set the table data to display.

confirmPhrase: (string)
  The value someone must answer to confirm his/her action.

theme: (string)
  Used to adjust the appearance of the confirmation modal by publishing the view.

metaData: (array)
  Pass any additional data to the confirmation modal.

modalBehavior: (array)
  Set the confirmation modal behavior (e.g., close-on-escape).

modalAttributes: (array)
  Set the confirmation modal attributes like the size.
```

--------------------------------

### Import and Compile Component JavaScript

Source: https://wire-elements.dev/getting-started/insert-component

The Insert Component requires custom JavaScript. Import the script in your `resources/js/bootstrap.js` file and ensure you have the `textarea-caret` NPM dependency installed before compiling your application's assets.

```javascript
import '../../vendor/wire-elements/pro/resources/js/insert-component.js'
```

--------------------------------

### Define a Query for a Specific Mode in PHP

Source: https://wire-elements.dev/getting-started/spotlight-component

This example shows how to create a query specifically for the 'help' mode using SpotlightQuery::forMode. Instead of navigating, it uses the `replace_query` action to change the user's input, effectively switching them to another mode like 'search_issues'.

```PHP
SpotlightQuery::forMode('help', function ($query) {

    return collect([
        SpotlightResult::make()
            ->setTitle('Search for issues, pull requests, discussions and projects')
            ->setTypeahead('Search mode')
            ->setAction('replace_query', ['query' => '#', 'description' => 'Start command'])
            ->setIcon('search'),
        SpotlightResult::make()
            ->setTitle('Activate command mode')
            ->setTypeahead('Command mode')
            ->setAction('replace_query', ['query' => '>', 'description' => 'Start command'])
            ->setIcon('terminal'),
    ])->when(!blank($query), function ($collection) use ($query) {
        return $collection->where(fn(SpotlightResult $result) => str($result->title())->lower()->contains(str($query)->lower()));
    });
})
```

--------------------------------

### Import Wire Elements Pro CSS

Source: https://wire-elements.dev/getting-started/insert-component

Import the component's CSS into your main `resources/css/app.css` file. This approach allows for easy customization of the component's appearance without editing the blade files directly. The example also shows how to add custom styles, such as disabling animations for reduced motion.

```css
@import "../../vendor/wire-elements/pro/resources/css/tailwind/insert-component.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

// Add your customizations here

// Example: Disable the transition animation when reduced motion is enabled
.wep-modal-content,
.wep-slide-over-container-inner-wrap {
    @apply motion-reduce:transition-none;
}
```

--------------------------------

### Return Static Pages as Spotlight Results

Source: https://wire-elements.dev/getting-started/spotlight-component

This example shows how to return a static page as a default result in Spotlight. It involves creating a collection and pushing a new `SpotlightResult` object to it, defining a title and a `jump_to` action with a path.

```php
class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        Spotlight::setup(function () {
            Spotlight::registerQueries(
                SpotlightQuery::asDefault(function ($query) {
                    $collection = collect();

                    $collection->push(
                        SpotlightResult::make()
                            ->setTitle('Dashboard')
                            ->setAction('jump_to', ['path' => '/'])
                    );

                    return $collection;
                });
            );
        });
    }
}
```

--------------------------------

### InsertQueryResult Properties

Source: https://wire-elements.dev/getting-started/insert-component

The `InsertQueryResult` object structures each item returned by the `search` method. It accepts several properties to define the content and behavior of each result in the insert component's dropdown.

```APIDOC
id: Unique identifier for given result
headline: The headline to be shown
subheadline: The subheadline to be shown (defaults to null and will be hidden)
photo: The photo to be shown (defaults to null and will be hidden)
insert: The string to insert if the user selects given query result
dispatch: Array of events to dispatch if the user chooses a given query result
view: Override the view to use for given query result
```

--------------------------------

### Include Published Assets Directly in Layout

Source: https://wire-elements.dev/getting-started/insert-component

After publishing the assets, link the CSS stylesheet in the `<head>` and include the JavaScript file before the closing `</body>` tag in your layout. This method bypasses the need for asset compilation.

```blade
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <title>Laravel</title>

    <!-- Include the insert-component.css stylesheet -->
    <link rel="stylesheet" href="{{ asset('vendor/wire-elements-pro/css/bootstrap-insert-component.css') }}">

    @livewireStyles
</head>
<body>

    <!-- //.... -->

    <!-- Include the insert-component.js script -->
    <script src="{{ asset('vendor/wire-elements-pro/js/insert-component.js') }}"></script>
</body>
</html>
```

--------------------------------

### Create a New Livewire Component

Source: https://wire-elements.dev/getting-started/slide-over-component

Use the standard `livewire:make` Artisan command to create a new Livewire component. This will serve as the foundation for your slide-over.

```bash
php artisan livewire:make UsersOverview
```

--------------------------------

### Publish the Package Configuration File

Source: https://wire-elements.dev/getting-started/spotlight-component

Run the `php artisan vendor:publish` command with the `wire-elements-pro-config` tag to copy the default configuration file into your application's `config` directory. This allows you to customize the default behavior and attributes of the components.

```bash
php artisan vendor:publish --tag=wire-elements-pro-config

Copied File [/wire-elements-pro/config/wire-elements-pro.php] To [/config/wire-elements-pro.php]
Publishing complete.
```

--------------------------------

### Add the Insert Base Component to Your Layout

Source: https://wire-elements.dev/getting-started/insert-component

Include the `@livewire('insert-pro')` Blade directive in your main application layout, such as `resources/views/layouts/app.blade.php`. This makes the insert functionality available on every page that uses this layout.

```blade
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <title>Laravel</title>

    @livewireStyles
</head>
<body>

    <!-- Require the Insert Pro component -->
    @livewire('insert-pro')

    @livewireScripts
</body>
</html>
```

--------------------------------

### Use the 'dispatch_event' Action in a Spotlight Result

Source: https://wire-elements.dev/getting-started/spotlight-component

Spotlight includes a built-in `dispatch_event` action for triggering events, such as opening a modal. This example shows how to configure a `SpotlightResult` to dispatch a `modal.open` event with specific data when selected.

```php
SpotlightResult::make()
    ->setTitle('Edit Product')
    ->setAction('dispatch_event', [
            'name' => 'modal.open',
            'data' => [
                'edit-product',
                ['productId' => $product->id]
            ],
            // The following two options are useful when triggering destructive actions.
            // For example, when a user scope is applied, you want to remove this scope if the user
            // uses a Spotlight command to trigger te deletion of a user.

            // If you set clearScope to true, the scope will be cleared if Spotlight is opened again
            // 'clearScope' => true,

            // If popScope is true, the scope will move up one level if Spotlight is opened again
            // 'popScope' => true,
            ])
```

--------------------------------

### Run Automated Upgrade for Livewire v3

Source: https://wire-elements.dev/getting-started/upgrade-guide

If you have already upgraded your application to Livewire v3, you can run this specific artisan command to review and apply the necessary upgrade steps for Wire Elements Pro.

```bash
php artisan livewire:upgrade --run-only wire-elements-pro-upgrade
```

--------------------------------

### Publish Wire Elements Pro Configuration

Source: https://wire-elements.dev/getting-started/upgrade-guide

Run this Artisan command to publish the latest configuration file for Wire Elements Pro. Using the `--force` flag is necessary to overwrite any existing configuration file with the updated version.

```bash
php artisan vendor:publish --tag=wire-elements-pro-config --force
```

--------------------------------

### Define a Basic InsertType Class in PHP

Source: https://wire-elements.dev/getting-started/insert-component

Create a new class that extends `InsertType`. Define the `delimiter` property (e.g., '@') to trigger the component and a `match` property with a regex pattern to validate the input that follows the delimiter.

```php
namespace App\InsertTypes;

class UserInsert extends InsertType
{
    protected string $delimiter = '@';
    protected string $match = '\w{1,20}$';
}
```

--------------------------------

### Define a Basic Livewire Slide-Over Component in PHP

Source: https://wire-elements.dev/getting-started/slide-over-component

Create a basic slide-over component by extending the `SlideOver` class. This example shows the default structure with empty `behavior()` and `attributes()` static methods, which can be overridden to customize the component's appearance and functionality.

```PHP
namespace App\Http\Livewire;

use WireElements\Pro\Components\SlideOver\SlideOver;

class UsersOverview extends SlideOver
{
    public function render()
    {
        return view('livewire.users-overview');
    }

    public static function behavior(): array
    {
        return [];
    }

    public static function attributes(): array
    {
        return [];
    }
}
```

--------------------------------

### Define a Spotlight Query for a Specific Token in PHP

Source: https://wire-elements.dev/getting-started/spotlight-component

This example illustrates how to define a query that executes only when a specific token is active. The `SpotlightQuery::forToken` method is used to associate a query with the 'repository' token, allowing for context-specific search logic separate from the default query.

```php
Spotlight::registerQueries(
    SpotlightQuery::asDefault(function ($query) {
            //...
    }),
    SpotlightQuery::forToken('repository', function (SpotlightScopeToken $repositoryToken, $query) {
        //...
    }),
);
```

--------------------------------

### Implement the Search Method for an InsertType

Source: https://wire-elements.dev/getting-started/insert-component

Add a `search` method to your `InsertType` class. This method receives the user's query, fetches matching data from a model, and returns the results formatted as an `InsertQueryResults` collection containing `InsertQueryResult` objects.

```php
namespace App\InsertTypes;

use App\Models\User;
use Illuminate\Support\Str;
use WireElements\Pro\Components\Insert\InsertQueryResult;
use WireElements\Pro\Components\Insert\InsertQueryResults;

class UserInsert extends InsertType
{
    protected string $delimiter = '@';
    protected string $match = '\w{1,20}$';

    public function search($query): InsertQueryResults
    {
        return InsertQueryResults::make(
            User::query()
                ->where('name', 'like', "%{$query}%")
                ->orWhere('handle', 'like', "%{$query}%")
                ->orderBy('name')
                ->get()
                ->map(function ($user) {
                    return InsertQueryResult::make(
                        id: $user->id,
                        headline: $user->name,
                        subheadline: '@' . $user->handle,
                        photo: sprintf('https://ui-avatars.com/api/?name=%s', urlencode($user->name)),
                        insert: '@' . $user->handle,
                        // view: 'different-blade-file',
                    );
                }));
    }
}
```

--------------------------------

### Implement Search Filtering for Spotlight Queries

Source: https://wire-elements.dev/getting-started/spotlight-component

To enable dynamic searching, you can filter your results collection based on the user's input. This example enhances the query registration by using the collection's `when` method to filter results where the title contains the search query string.

```php
Spotlight::registerQueries(
    SpotlightQuery::asDefault(function ($query) {
        $collection = collect();

        $collection->push(
            SpotlightResult::make()
                ->setTitle('Dashboard')
                ->setGroup('pages')
                ->setAction('jump_to', ['path' => '/'])
                ->setIcon('home'),
            SpotlightResult::make()
                ->setTitle('Repositories')
                ->setTypeahead('Your Repositories') // If you want to set a different typeahead (placeholder in the input field)
                ->setGroup('pages')
                ->setAction('jump_to', ['path' => route('repositories')])
                ->setIcon('repository'),
        );

        $collection = $collection->when(!blank($query), function ($collection) use ($query) {
            return $collection->where(fn(SpotlightResult $result) => str($result->title())->lower()->contains(str($query)->lower()));
        });

        return $collection;
    })
);
```

--------------------------------

### Create a Livewire Modal with Data Properties

Source: https://wire-elements.dev/getting-started/modal-component

Define a Livewire modal component that accepts data by declaring public properties and using the `mount` method for dependency injection or initialization. This example shows an `EditUser` modal that requires a `User` object to be passed.

```php
class EditUser extends Modal
{
    public int|User $user;

    public function mount(User $user) {
        $this->user = $user;
    }

    public function render()
    {
        return view('livewire.edit-user');
    }
}
```

--------------------------------

### Register Static Spotlight Queries

Source: https://wire-elements.dev/getting-started/spotlight-component

This snippet demonstrates how to register a default set of static results for Spotlight. It uses `SpotlightQuery::asDefault` to create a collection of `SpotlightResult` objects, each configured with a title, group, icon, and a `jump_to` action.

```php
Spotlight::registerQueries(
    SpotlightQuery::asDefault(function ($query) {
        $collection = collect();

        $collection->push(
            SpotlightResult::make()
                ->setTitle('Dashboard')
                ->setTypeahead('Dashboard')
                ->setGroup('pages')
                ->setAction('jump_to', ['path' => '/'])
                ->setIcon('home'),
            SpotlightResult::make()
                ->setTitle('Repositories')
                ->setTypeahead('Repositories')
                ->setGroup('pages')
                ->setAction('jump_to', ['path' => route('repositories')])
                ->setIcon('repository'),
        );

        return $collection;
    }),
);
```

--------------------------------

### Register a Spotlight Group in a Service Provider

Source: https://wire-elements.dev/getting-started/spotlight-component

To organize Spotlight results, you can register groups. This example shows how to register a 'pages' group within the `register` method of an `AppServiceProvider` using the `Spotlight::registerGroup` static method.

```php
class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        Spotlight::registerGroup('pages', 'Pages');

        // ...
    }
}
```

--------------------------------

### Register Wire Elements Pro Service Provider in Laravel

Source: https://wire-elements.dev/getting-started/installation

If Laravel's package auto-discovery is disabled in your application, you must manually register the `WireElementsProServiceProvider` in your `config/app.php` file. Add the service provider's class to the `providers` array to ensure the package is loaded correctly by your application.

```php
{
    /*
    |--------------------------------------------------------------------------
    | Autoloaded Service Providers
    |--------------------------------------------------------------------------
    |
    | The service providers listed here will be automatically loaded on the
    | request to your application. Feel free to add your own services to
    | this array to grant expanded functionality to your applications.
    |
    */

    'providers' => [
        // ...
        WireElements\Pro\WireElementsProServiceProvider::class,
    ]
}
```

--------------------------------

### Register Random Tips in PHP

Source: https://wire-elements.dev/getting-started/spotlight-component

This code demonstrates how to register a list of random tips that can be displayed in the Spotlight command palette. The Spotlight::registerTips method accepts multiple string arguments, each representing a tip.

```PHP
Spotlight::registerTips(

    __('Type <kbd>#</kbd> to do magic'),
    __('Be mindful. Be grateful. Be positive. Be true. Be kind.'),
    __('Pursue what catches your heart, not what catches your eyes.'),
    __('Do not fear failure but rather fear not trying.'),
);
```

--------------------------------

### Enable Insert Component on HTML Inputs

Source: https://wire-elements.dev/getting-started/insert-component

Apply the insert functionality to an HTML input or textarea. Use the `wep_insert` Blade directive for inputs and the `@insert` directive for textareas, passing the key defined in your configuration (e.g., 'user').

```html
<input type="text" {{ wep_insert(['user']) }} placeholder="Enter username">

<textarea rows="5" @insert(user) placeholder="Description"></textarea>
```

--------------------------------

### Register Wire Elements Pro Service Provider in Laravel

Source: https://wire-elements.dev/index

If you have disabled Laravel's auto-discovery feature, you must manually register the `WireElementsProServiceProvider` in your `config/app.php` file. This step is typically not required in modern Laravel applications.

```php
{
    /*
    |--------------------------------------------------------------------------
    | Autoloaded Service Providers
    |--------------------------------------------------------------------------
    |
    | The service providers listed here will be automatically loaded on the
    | request to your application. Feel free to add your own services to
    | this array to grant expanded functionality to your applications.
    |
    */

    'providers' => [
        // ...
        WireElements\Pro\WireElementsProServiceProvider::class,
    ]
}
```

--------------------------------

### Configure Tailwind CSS Content Paths

Source: https://wire-elements.dev/getting-started/insert-component

To ensure Tailwind CSS generates the required styles for Wire Elements Pro components, add the package's configuration and view paths to the `content` array in your `tailwind.config.js` file.

```javascript
module.exports = {

    content: [
        './vendor/wire-elements/pro/config/wire-elements-pro.php',
        './vendor/wire-elements/pro/**/*.blade.php',
    ],

        //....
};
```

--------------------------------

### Create a Slide-Over Component that Accepts Properties in PHP

Source: https://wire-elements.dev/getting-started/slide-over-component

Define a Livewire slide-over component that accepts properties, such as a model instance. The `mount` method is used to initialize the component's state with the passed arguments, making them available to the component and its view.

```PHP
class EditUser extends SlideOver
{
    public int|User $user;

    public function mount(User $user) {
        $this->user = $user;
    }

    public function render()
    {
        return view('livewire.edit-user');
    }
}
```

--------------------------------

### Publish Wire Elements Pro Configuration File

Source: https://wire-elements.dev/getting-started/slide-over-component

Run this Artisan command to publish the Wire Elements Pro configuration file to your application's `config` directory. This allows you to customize the default behavior and attributes of the components.

```bash
php artisan vendor:publish --tag=wire-elements-pro-config
```

--------------------------------

### Create a Slide-Over View with Blade

Source: https://wire-elements.dev/getting-started/insert-component

This Blade template defines the user interface for a slide-over component used to add a link. It includes input fields for a title and a link, bound to Livewire properties using `wire:model.live`. The form submission is handled by the `insert` method in the component class.

```blade
<x-wire-elements-pro::tailwind.slide-over on-submit="insert">
    <x-slot name="title">Add link</x-slot>

    <div>
        <div>
            <label for="title">Title</label>
            <div class="mt-1">
                <input type="text" wire:model.live="title" id="title">
            </div>

            @error("title")
                <p>{{ $message }}</p>
            @enderror
        </div>

        <div>
            <label for="link">Link</label>
            <div class="mt-1">
                <input type="text" wire:model.live="link" id="link">
            </div>

            @error("link")
                <p>{{ $message }}</p>
            @enderror
        </div>

        <div>
            <button type="button" wire:click="$dispatch('slide-over.close')">
                Cancel
            </button>

            <button type="submit">
                Add link
            </button>
        </div>
    </div>
</x-wire-elements-pro::tailwind.slide-over>
```

--------------------------------

### Open a Livewire Modal and Pass Arguments

Source: https://wire-elements.dev/getting-started/modal-component

Illustrates how to pass data to a modal component when opening it. Arguments can be supplied from JavaScript, Blade templates, or a parent Livewire component to initialize the modal's state.

```javascript
Livewire.dispatch('modal.open', {component: 'edit-user', arguments: {'user': 1}});
```

```blade
<button onclick="Livewire.dispatch('modal.open', {component: 'edit-user', arguments: {'user': 1}})">Open</button>
```

```blade
<button wire:modal="edit-user, @js(['user' => 1])">Open</button>
```

```blade
<button wire:click="$dispatch('modal.open', {component: 'edit-user', arguments: {'user': 1}})">Open</button>
```

```php
$this->dispatch('modal.open', component: 'edit-user', arguments: ['user' => 1]);
```

--------------------------------

### Import Wire Elements Pro Styles

Source: https://wire-elements.dev/getting-started/spotlight-component

Import the package's default styles into your main CSS file, such as `resources/css/app.css`. This allows you to apply the base styles and add your own customizations or overrides for components like the modal.

```css
@import "../../vendor/wire-elements/pro/resources/css/tailwind/spotlight-component.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

// Add your customizations here

// Example: Disable the transition animation when reduced motion is enabled
.wep-modal-content,
.wep-slide-over-container-inner-wrap {
    @apply motion-reduce:transition-none;
}
```

--------------------------------

### Listen for Events in a Livewire Component

Source: https://wire-elements.dev/getting-started/slide-over-component

A Livewire component can listen for events dispatched from a closing slide-over by defining a `getListeners()` method. This allows the component to react to the event, for example, by refreshing its own data using `$refresh`.

```php
class UsersOverview extends SlideOver
{
    public function getListeners()
    {
        return ['userDeleted' => '$refresh']; // Refresh the component
    }

    public function render()
    {
        return view('livewire.users-overview');
    }
}
```

--------------------------------

### Create a Livewire Component for the Modal

Source: https://wire-elements.dev/getting-started/modal-component

Use the standard `livewire:make` Artisan command to create a new Livewire component. This component will contain the logic and render the view for your modal.

```bash
php artisan livewire:make UsersOverview
```

--------------------------------

### Register the Insert Component Service Provider

Source: https://wire-elements.dev/getting-started/insert-component

To enable the Insert Component, you need to register its service provider in your Laravel application's `config/app.php` file. This ensures that the component's assets and services are correctly loaded by the framework.

```php
'providers' => [

        /*
         * Laravel Framework Service Providers...
         */
        Illuminate\Auth\AuthServiceProvider::class,

        /*
         * Package Service Providers...
         */
        WireElements\Pro\Components\Insert\InsertServiceProvider::class,
]
```

--------------------------------

### Configure Insert Types in PHP

Source: https://wire-elements.dev/getting-started/insert-component

To enable the insert component, you must register one or more `InsertType` classes in the `config/wire-elements-pro.php` file. This configuration maps a key, like 'user', to its corresponding PHP class and sets default behaviors such as debounce delay.

```php
return [
    'default' => 'tailwind',
    'components' => [
    'insert' => [
            'view' => 'wire-elements-pro::insert.component',
            'types' => [
                'user' => \App\Insert\UserInsert::class,
                // Examples of a different insert types
                'ticket' => \App\Insert\TicketInsert::class,
                'command' => \App\Insert\CommandInsert::class,
            ],
            'default-behavior' => [
                'debounce_milliseconds' => 200, // Delay before requesting the query results to prevent requests on every keystroke.
                'show_keyboard_instructions' => true, // Display the keyboard instructions (arrows + enter key)
            ]
        ]
        // Other components
    ]
];
```

--------------------------------

### Register a Default Spotlight Query in PHP

Source: https://wire-elements.dev/getting-started/spotlight-component

This code demonstrates how to register a default query that searches for repositories and pages. It uses SpotlightResult::make() to format the results and setTokens() to associate data with a result, enabling features like scoped searching.

```PHP
Spotlight::registerQueries(

    SpotlightQuery::asDefault(function ($query) {

        $pages = collect(
            //...
        );

        $repositories = Repository::query()
            ->when(!blank($query), fn($q) => $q->where('name', 'like', "%{$query}%"))
            ->get()->map(function ($repository) {
                return SpotlightResult::make()
                    ->setTitle($repository->name)
                    ->setGroup('repositories')
                    ->setAction('jump_to', ['path' => route('repository.show', $repository)])
                    ->setTokens(['repository' => $repository])
                    ->setIcon('repository');
            });

        return collect()->merge($repositories)->merge($pages);
    })
);
```

--------------------------------

### Listen for Events in a Livewire Component

Source: https://wire-elements.dev/getting-started/modal-component

To react to an event dispatched from a closed modal, a Livewire component can define its listeners in the `getListeners()` method or `$listeners` property. In this example, the `UsersOverview` component listens for the `userDeleted` event and refreshes itself.

```php
class UsersOverview extends Modal
{
    public function getListeners()
    {
        return ['userDeleted' => '$refresh']; // Refresh the component
    }

    public function render()
    {
        return view('livewire.users-overview');
    }
}
```

--------------------------------

### Implement the Slide-Over Component Logic in PHP

Source: https://wire-elements.dev/getting-started/insert-component

This is the Livewire component class for the 'Link' slide-over. It uses the `InteractsWithInsertComponent` trait to communicate back to the parent component. The `insert` method validates the user input, formats the link in Markdown style, and sends it for insertion using `insertValue()` before closing the slide-over.

```php
use WireElements\Pro\Components\Insert\InteractsWithInsertComponent;
use WireElements\Pro\Components\SlideOver\SlideOver;

class Link extends SlideOver
{
    // Include the trait in order to be able to send values back to your input
    use InteractsWithInsertComponent;

    public $title;
    public $link;

    public $rules = [
        'title' => ['required'],
        'link' => ['required', 'url'],
    ];

    public function insert()
    {
        $this->validate();

        // Call the insertValue method with the value you want to insert.
        $this->insertValue("[{$this->title}]({$this->link})");

        // Be sure to close the slide-over once you've send over the value to insert.
        $this->close();
    }

    public function render()
    {
        return view('livewire.link');
    }
}
```

--------------------------------

### Define Custom Insert Commands in PHP

Source: https://wire-elements.dev/getting-started/insert-component

This PHP class `CommandInsert` extends `InsertType` to create custom slash commands. It defines a search method that returns a collection of commands, such as 'Insert image' and 'Insert link'. Instead of directly inserting text, these commands dispatch Livewire events to open corresponding slide-over components.

```php
class CommandInsert extends InsertType
{
    protected string $delimiter = '/';
    protected string $match = '\w*$';

    public function search($query): InsertQueryResults
    {
        return InsertQueryResults::make(
            // Create a static array with different commands
            collect([
                [
                    'name' => 'Insert image',
                    'subheadline' => 'Choose from the image library',

                    // Instead of inserting a value we will dispatch the event to open a slide-over
                    'dispatch' => [
                        'slide-over.open' => ['media-library'],
                        // You can also pass properties, element attributes and behavior
                        'slide-over.open' => [
                            'some-other-slide-over', // Component
                            ['param1' => 'x', 'param2' => 'y'] // Properties !!(this must be a key value array)!!
                            ['size' => '6xl'], // Element attributes
                            ['close-on-escape' => false, 'trap-focus' => true], // Element behavior
                        ],
                    ],
                ],
                [
                    'name' => 'Insert link',
                    'subheadline' => 'Add external link',

                    // Instead of inserting a value we will dispatch the event to open a slide-over
                    'dispatch' => [
                        'slide-over.open' => ['link'],
                    ],
                ]
            ])
            // We only 'search' if a query string is provided, if the string is empty we want to return all the commands
            // This will ensure the user can see the available commands when they only type the "/" character.
            ->unless(empty($query), fn($q) => $q->filter(fn($command) => str($command['name'])->lower()->contains($query)))
            // Finally, we map the commands into the InsertQueryResult object
            ->map(function ($command, $id) {
                return InsertQueryResult::make(
                    id: $id,
                    headline: $command['name'],
                    dispatch: $command['dispatch'],
                    subheadline: $command['subheadline'],
                );
            })
        );
    }
}
```

--------------------------------

### Publish Wire Elements Pro Assets

Source: https://wire-elements.dev/getting-started/spotlight-component

As an alternative to compiling assets, you can publish them directly to your application's public directory using an Artisan command. This is useful for including the JavaScript and CSS files without a build step and is required for the Bootstrap preset.

```shell
php artisan vendor:publish --tag=wire-elements-pro-assets

Copied Directory [/wire-elements-pro/resources/dist] To [/public/vendor/wire-elements-pro]
Publishing complete.
```

--------------------------------

### Enable Multiple Insert Types on an Input

Source: https://wire-elements.dev/getting-started/insert-component

To allow multiple insert types, such as mentioning users and referencing tickets in the same field, pass an array of keys to the `wep_insert` function. This enables the component to recognize and handle different trigger characters or patterns.

```html
<input type="text" {{ wep_insert(['user', 'ticket']) }} placeholder="Enter username">

<textarea rows="5" {{ wep_insert(['user', 'ticket']) }} placeholder="Description"></textarea>
```

--------------------------------

### Implement a Basic Confirmation Modal in PHP

Source: https://wire-elements.dev/getting-started/modal-component

To use the confirmation modal, include the `InteractsWithConfirmationModal` trait in your Livewire component. Then, call the `askForConfirmation` method, providing a callback function that contains the logic to be executed upon confirmation.

```php
use WireElements\Pro\Concerns\InteractsWithConfirmationModal;

class UsersOverview extends Modal
{
    use InteractsWithConfirmationModal;

    public function delete($userId)
    {
        $this->askForConfirmation(
            callback: function() use ($userId) {
                User::find($userId)?->delete();
            },
        );
    }

    public function render()
    {
        return view('livewire.user-overview');
    }
}
```

--------------------------------

### Implement the InsertType PHP Class

Source: https://wire-elements.dev/getting-started/insert-component

Create a class that extends `InsertType` to define the behavior for a specific insert type. In this class, you specify the delimiter character (e.g., '@'), a regex pattern for matching, and implement the `search` method to query for results based on user input and any scoped data provided.

```php
class UserInsert extends InsertType
{
    protected string $delimiter = '@';
    protected string $match = '\w{1,20}$';

    public function search($query, $scope): InsertQueryResults
    {
        // var_dump($scope) -> [1,2,3]
        return InsertQueryResults::make(...);
    }
}
```

--------------------------------

### Import Spotlight Component JavaScript

Source: https://wire-elements.dev/getting-started/spotlight-component

The Spotlight component relies on custom JavaScript. You must import its script into your application's main JavaScript file, such as `resources/js/bootstrap.js`, and then compile your assets. This process also requires the `@alpinejs/focus` NPM package as a dependency.

```javascript
import '../../vendor/wire-elements/pro/resources/js/spotlight-component.js'
```

--------------------------------

### Register a Spotlight Scope for a Route in PHP

Source: https://wire-elements.dev/getting-started/spotlight-component

This snippet shows how to register a `SpotlightScope` that activates on a specific route. When the 'repository.show' route is visited, this scope applies the 'repository' token using data from the incoming request, making the command palette aware of the current repository context.

```php
Spotlight::registerScopes(
    SpotlightScope::forRoute('repository.show', function (SpotlightScope $scope, Request $request) {
        $scope->applyToken('repository', $request->repository);
    })
);
```

--------------------------------

### Publish Package Assets with Artisan

Source: https://wire-elements.dev/getting-started/slide-over-component

To include JavaScript and CSS directly without compiling, publish the package's assets using the `php artisan vendor:publish` command with the `wire-elements-pro-assets` tag. This copies the necessary files to your public directory.

```bash
php artisan vendor:publish --tag=wire-elements-pro-assets
```

--------------------------------

### Define a Custom SVG Icon for Spotlight

Source: https://wire-elements.dev/getting-started/spotlight-component

This code shows how to create a custom icon class by extending `WireElements\Pro\Icons\Icon`. The `svg()` method must be implemented to return the raw SVG markup for the icon, which can then be registered in the configuration.

```php
use WireElements\Pro\Icons\Icon;

class MyIcon extends Icon
{
    public function svg(): string
    {
        return <<<'blade'
          <svg fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6"></path></svg>
          blade;
    }
}
```

--------------------------------

### Customize SpotlightResult with Additional Properties

Source: https://wire-elements.dev/getting-started/spotlight-component

This snippet illustrates how to further customize a `SpotlightResult` object by chaining various methods. It demonstrates setting a typeahead placeholder, assigning the result to a group, defining an action, and specifying an icon.

```php
Spotlight::setup(function () {
    Spotlight::registerQueries(
        SpotlightQuery::asDefault(function ($query) {
            $collection = collect();

            $collection->push(
                SpotlightResult::make()
                    ->setTitle('Dashboard')
                    ->setTypeahead('Dashboard')
                    ->setGroup('pages')
                    ->setAction('jump_to', ['path' => '/'])
                    ->setIcon('home')
            );

            return $collection;
        }),
    );
});
```

--------------------------------

### Register Spotlight Service Provider in Laravel

Source: https://wire-elements.dev/getting-started/spotlight-component

To enable the Spotlight component, register its service provider in your Laravel application's `config/app.php` file. This step is crucial for loading the component's required assets and services.

```php
'providers' => [

        /*
         * Laravel Framework Service Providers...
         */
        Illuminate\Auth\AuthServiceProvider::class,

        /*
         * Package Service Providers...
         */
        WireElements\Pro\Components\Spotlight\SpotlightServiceProvider::class,
]
```

--------------------------------

### Register a Custom Spotlight Action

Source: https://wire-elements.dev/getting-started/spotlight-component

After creating a custom action class, you must register it with Spotlight. This is done by calling the `Spotlight::registerAction` method, mapping a string key ('jump_to') to your custom action class (`JumpTo::class`).

```php
Spotlight::registerAction('jump_to', JumpTo::class);
```

--------------------------------

### Pass Scoped Data to the Insert Component

Source: https://wire-elements.dev/getting-started/insert-component

You can pass additional data to the insert component to scope the search results. This is useful for limiting mentions to users who are part of a specific discussion. The data is passed as a second argument to the `wep_insert` directive and is available in the `search` method of your `InsertType` class.

```html
<textarea rows="5" {{ wep_insert(['user'], [1,2,3]) }} placeholder="Description"></textarea>
```

--------------------------------

### Update Insert Component Syntax in Blade

Source: https://wire-elements.dev/getting-started/upgrade-guide

The `@insert` Blade directive has been deprecated and replaced by the `wep_insert` helper function. This example shows the old syntax versus the new, required syntax. The new helper also supports passing an optional array of data as a second argument.

```html
<!-- Before -->
<textarea @insert(user,command)></textarea>

<!-- After -->
<textarea {{ wep_insert(['user', 'command']) }}></textarea>
<!-- Adding data is only supported by using the wep_insert function -->
<textarea {{ wep_insert(['user', 'command'], [1,2,3]) }}></textarea>
```

--------------------------------

### Publish Wire Elements Pro Assets

Source: https://wire-elements.dev/getting-started/modal-component

To include JavaScript and CSS directly without compiling, publish the package assets using this Artisan command. This copies the necessary files from the vendor directory to your application's `public` directory.

```shell
php artisan vendor:publish --tag=wire-elements-pro-assets
```

--------------------------------

### Configure Confirmation Modal Views in PHP

Source: https://wire-elements.dev/getting-started/modal-component

Customize the confirmation modal's template by publishing the views or by specifying a different view file in the `wire-elements-pro.php` config. This allows for different templates based on presets like Tailwind or Bootstrap.

```php
return [
    'default' => 'tailwind',

    'components' => [...],

    'presets' => [
        'tailwind' => [
            'modal' => [
                'size-map' => [...],
                'confirmation_view' => 'wire-elements-pro::modal.tailwind.confirmation',
            ]
        ],
        'bootstrap' => [
            'modal' => [
                'size-map' => [...],
                'confirmation_view' => 'wire-elements-pro::modal.bootstrap.confirmation',
            ]
        ],
    ],
]
```

--------------------------------

### Include Published Assets Directly in Layout

Source: https://wire-elements.dev/getting-started/slide-over-component

After publishing the assets, you can link the CSS and JavaScript files directly in your main layout. This is an alternative to compiling them and is required if you are using the Bootstrap preset.

```blade
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <title>Laravel</title>

    <!-- Include the overlay-component.css stylesheet -->
    <link rel="stylesheet" href="{{ asset('vendor/wire-elements-pro/css/bootstrap-overlay-component.css') }}">

    @livewireStyles
</head>
<body>

    <!-- //.... -->

    <!-- Include the overlay-component.js script -->
    <script src="{{ asset('vendor/wire-elements-pro/js/overlay-component.js') }}"></script>
</body>
</html>
```

--------------------------------

### Set Bootstrap as the Default Preset

Source: https://wire-elements.dev/getting-started/slide-over-component

If you are using the Bootstrap front-end framework instead of Tailwind CSS, you must change the `default` preset to `bootstrap` in the published `config/wire-elements-pro.php` file.

```php
return [
    'default' => 'bootstrap',

    // ...
];
```

--------------------------------

### Add SlideOverServiceProvider to Laravel Config

Source: https://wire-elements.dev/getting-started/slide-over-component

To enable the Slide-over component, register the `SlideOverServiceProvider` in your `config/app.php` file within the `providers` array. This ensures that the necessary assets and services for the component are loaded by the Laravel application.

```php
'providers' => [

        /*
         * Laravel Framework Service Providers...
         */
        Illuminate\Auth\AuthServiceProvider::class,

        /*
         * Package Service Providers...
         */
        WireElements\Pro\Components\SlideOver\SlideOverServiceProvider::class,
]
```

--------------------------------

### Publish Wire Elements Pro Configuration

Source: https://wire-elements.dev/getting-started/modal-component

Run this Artisan command to publish the Wire Elements Pro configuration file to your application's `config` directory. This allows you to customize default modal behaviors and attributes, such as switching the front-end framework preset.

```bash
php artisan vendor:publish --tag=wire-elements-pro-config
```

--------------------------------

### Import and Compile Modal Component JavaScript

Source: https://wire-elements.dev/getting-started/modal-component

The Modal component requires custom JavaScript. Import the `overlay-component.js` script into your application's main JavaScript file, such as `resources/js/bootstrap.js`, to ensure it's compiled with your other assets.

```javascript
import '../../vendor/wire-elements/pro/resources/js/overlay-component.js'
```

--------------------------------

### Register Command Palette Modes in PHP

Source: https://wire-elements.dev/getting-started/spotlight-component

This snippet shows how to register different modes for the command palette using Spotlight::registerModes. Each mode is defined by a unique identifier, a description, and a character that triggers it, such as '?' for help or '#' for searching issues.

```PHP
Spotlight::registerModes(

    SpotlightMode::make('help', 'Command palette tips and tricks')
        ->setCharacter('?'),
    SpotlightMode::make('search_issues', 'Search issues and pull requests')
        ->setCharacter('#'),
    SpotlightMode::make('global_commands', 'Global Commands')
        ->setCharacter('>'),
);
```

--------------------------------

### Customize the Insert Item View with Blade

Source: https://wire-elements.dev/getting-started/insert-component

You can override the default view for a specific query result by passing a Blade template name to the `view` property. Inside your custom template, use the `x-wire-elements-pro::insert-item` component to ensure proper functionality, which provides access to the `$result` and `$loop` variables.

```blade
<x-wire-elements-pro::insert-item :item="$result" :index="$loop->index">
    Look at me 😎 I'm a different blade template
</x-wire-elements-pro::insert-item>
```

--------------------------------

### Configure for Bootstrap Framework

Source: https://wire-elements.dev/getting-started/modal-component

If you are using Bootstrap instead of Tailwind CSS, you must change the `default` preset in the published `config/wire-elements-pro.php` file. Set the value from 'tailwind' to 'bootstrap' to use the correct styling and components.

```php
return [
    'default' => 'bootstrap',

    // ...
];
```
Tokens:
Raw