Skip to main content
Copy for LLM

Overlay Events

Every WireKit overlay component is event-controlled — you open it, close it, or scope it via $dispatch from Alpine or $this->dispatch(...) from a Livewire component. There's no programmatic JS API to import; the event vocabulary is the API, and the names in the matrix below keep working unchanged for the whole of v2.

This page is the reference for every overlay event the components listen for, with the payload shape and Livewire-side dispatch examples.

Event matrix

Component Event name Payload shape Notes
<x-wirekit::modal> wirekit-modal-show / wirekit-modal-close { name } Dismissible by default — backdrop click + ESC both close.
<x-wirekit::drawer> wirekit-drawer-show / wirekit-drawer-close { name } Same shape as modal. drawer.trigger sends the show event for you, from anywhere on the page.
<x-wirekit::alert-dialog> wirekit-alert-dialog-show / wirekit-alert-dialog-close { name } A click on the backdrop does nothing unless the dialog is dismissible; Escape always closes it.
<x-wirekit::command-palette> wirekit-command-palette-show / wirekit-command-palette-close optional { name }, and { query } on show Without a name it reaches every palette on the page except one with named-only; with one, only the palette whose name prop matches. A query opens the palette with that text in its field, see Opening with text. Escape closes it too, and so does choosing an item, after the item's own click handler has run.
<x-wirekit::tour> wirekit-tour-start-<name> (name suffixed into the event name) — (no detail) The tour's name prop is appended to the event with a hyphen separator. Example: <x-wirekit::tour name="onboarding"> listens for wirekit-tour-start-onboarding.
<x-wirekit::toast-region> wirekit-toast (global) or wirekit-toast-<name> (scoped) { title, message, variant, duration? } Different payload from the show/close family — toasts carry their own content.
<x-wirekit::lightbox> wirekit-lightbox-open { name, index } Opens the named lightbox at a given item.
<x-wirekit::command-palette> wirekit-command-palette-query { query } Dispatched by the palette, not listened for. It fires from the component root rather than the input, because the input teleports to <body> and an event fired there never passes the root.
<x-wirekit::command-palette> wirekit:command-palette-state { state, name? } Addressed like the palette's show and close events: every palette without a name, only the named one with it. state is loading, error or idle, and says where your remote search stands: the palette shows its loading or error slot and holds back the empty state meanwhile. Any other value counts as idle. A remote search shows it at work.
<x-wirekit::modal> wirekit:modal-dismissed { name, via } Dispatched by the modal, on the window, when the reader dismisses it: via is backdrop, escape or close-button. Never for a close the page asked for, so a cleanup it triggers runs once.
<x-wirekit::drawer> wirekit:drawer-dismissed { name, via } Dispatched by the drawer, the same as the modal's.

Shape detail

Most overlays take { name: 'unique-id' } where name matches the component's name="..." prop. Multiple overlays on the same page each listen for their own name; events targeted at a different name are ignored.

Command palette takes the show/close verbs of the family, and its payload is optional. Dispatched without one, $dispatch('wirekit-command-palette-show') opens every palette on the page and the close event closes every one, which is all a page with a single palette needs. A page with two gives each a name prop and puts the same name in the event, $dispatch('wirekit-command-palette-show', { name: 'search' }), and only that palette answers. The keyboard shortcut is not addressed by name, so set hotkey="" on all but one. A palette that must not answer the unnamed event at all, such as a site search beside demos, takes named-only. See Two palettes on one page.

Tour is the odd one out — instead of a payload, the tour's name is part of the event name itself. $dispatch('wirekit-tour-start-onboarding') starts the tour named onboarding; no payload object needed.

Toast is also irregular — instead of { name }, the payload carries the toast's content: { title, message, variant, duration? }. variant is one of info (the default), success, warning or danger. The scoping (which <x-wirekit::toast-region> instance picks up the event) goes by the event's name: regions with name="..." listen on wirekit-toast-<name>, regions without a name listen on the global wirekit-toast.

Examples — opening from Alpine (client-side)

The contract in one live block: a button that dispatches, a modal that listens, and a readout of what actually crossed the window. Open it, close it, and watch the two events arrive in order: the show the button sent, then the dismissal the modal reports, with the route the reader took.

Dispatching to a modal, and reading the events back

Last overlay event:

Discard your changes?

The name in the payload is what picks this modal out of however many are on the page: dispatch a different one and nothing opens. Every way the reader closes it reports the same event, wirekit:modal-dismissed, with via naming the way, so there is no separate signal per route to listen for. wirekit-modal-close is the command a page sends to close a modal, and the modal never sends it back.

Trigger a modal from a custom button outside the dialog markup:

<button x-on:click="$dispatch('wirekit-modal-show', { name: 'settings' })">
    Open settings
</button>

<x-wirekit::modal name="settings">
    <x-wirekit::modal.header>Settings</x-wirekit::modal.header>
    <x-wirekit::modal.body>
        ...
    </x-wirekit::modal.body>
</x-wirekit::modal>

Close from inside the modal (Cancel button):

<button x-on:click="$dispatch('wirekit-modal-close', { name: 'settings' })">
    Cancel
</button>

Open a tour by name:

<button x-on:click="$dispatch('wirekit-tour-start-onboarding')">
    Start tour
</button>

Show a toast — global region (single <x-wirekit::toast-region /> on the page):

<button x-on:click="$dispatch('wirekit-toast', {
    title: 'Saved',
    message: 'Your changes are live.',
    variant: 'success',
    duration: 4000
})">
    Save
</button>

Show a toast — scoped region (when multiple regions exist with different name="..." props):

<x-wirekit::toast-region name="critical" />
<x-wirekit::toast-region name="info" />

<button x-on:click="$dispatch('wirekit-toast-critical', {
    title: 'Connection lost',
    message: 'Retrying in 5s...',
    variant: 'danger'
})">
    Simulate connection loss
</button>

Examples — dispatching from Livewire (server-side)

Every Alpine $dispatch call has a 1:1 Livewire equivalent via $this->dispatch(...). Same event name; payload becomes named arguments.

Open a modal from a Livewire method:

public function openSettings(): void
{
    $this->dispatch('wirekit-modal-show', name: 'settings');
}

Show a toast as a flash after a server-side action:

public function save(): void
{
    // ... persist state ...

    $this->dispatch('wirekit-toast',
        title: 'Saved',
        message: 'Your changes are live.',
        variant: 'success',
        duration: 4000,
    );
}

Close an alert-dialog after a destructive confirmation runs:

public function deleteProject(): void
{
    // 1. The id is a public property the browser can change: check the reader may delete
    //    this project before anything goes.
    $project = Project::findOrFail($this->projectId);
    $this->authorize('delete', $project);

    $project->delete();

    $this->dispatch('wirekit-alert-dialog-close', name: 'delete-project');
}

Conventions and pitfalls

A few names in the vocabulary do not follow the pattern the rest of it does:

  1. The overlay events on this page use hyphens throughout — and they are the exception. $dispatch('wirekit:modal-show', …) silently does nothing; the shape these components listen for is $dispatch('wirekit-modal-show', …). This does not generalize. The library's convention is wirekit:<component>-<happening> — a colon after the namespace — and Events documents it as such: wirekit:tab-changed, wirekit:reveal, wirekit:inline-edit-confirmed, wirekit:reading-progress:milestone. The overlays keep the all-hyphen form for the whole of v2, so the rule to carry is "look the event up", not "WireKit does not use colons".
  2. <x-wirekit::tour> suffixes the name into the event itself, not the payload: wirekit-tour-start-onboarding starts the tour named onboarding, and a wirekit-tour-start with a { name } payload starts nothing.
  3. <x-wirekit::toast-region> uses variant, not intent. The toast payload key is variant: 'info' | 'success' | 'warning' | 'danger', where badge, alert and callout call their prop intent. See Prop Naming Conventions for the intent / surface / variant / tone family split and the alias matrix.
  4. Show events are fire-and-forget — the dispatcher gets no return value, and a modal or a drawer sends no event when it has opened. Each gives the focus to its first control: the close button of its header, or its first field when it has no header.

Was this page helpful?

Thank you for your feedback!

Voting requires cookies or local storage. What we store