---
title: Events
description: Every event WireKit dispatches, what it carries, and which of the three historical naming conventions it belongs to.
visibility: guest
related:
  - /overlays/events
  - /extending/authoring-custom-alpine-plugins
---

# Events

A dispatched event name is public API. Once you listen for one, renaming it breaks your code —
so this page lists **every event the catalog dispatches**, not a curated selection, and says
plainly which of them are on a convention we intend to keep.

For opening and closing overlays, [Overlay Events](/overlays/events) is the deeper reference:
it carries the payload shapes and the Livewire-side dispatch examples. This page is the complete
inventory.

## The convention

**`wirekit:<component>-<happening>`** — a colon after the namespace, hyphens inside the name.

```js
window.addEventListener('wirekit:tab-changed', (e) => console.log(e.detail));
```

The colon is not decoration. It separates the namespace from the name the way
`<x-wirekit::button>` does, and it cannot be mistaken for a CSS class or a hyphenated HTML
attribute — which a bare `wirekit-tab-changed` can. Where a name has a natural sub-scope, a
second colon groups it: `wirekit:reading-progress:milestone`.

::: info
Every component works on its own. These events exist so your application can react to what a
component did, if it wants to — a listener is an addition, not a prerequisite.
:::

## Listening from Alpine

:::preview{title="Reacting to a tab change"}
<x-wirekit::stack gap="md" x-data="{ last: '—' }" x-on:wirekit:tab-changed.window="last = $event.detail?.name ?? '—'">
    <x-wirekit::tabs :items="['overview' => 'Overview', 'activity' => 'Activity', 'settings' => 'Settings']" default="overview">
        <x-slot:overview><x-wirekit::text>Overview panel.</x-wirekit::text></x-slot:overview>
        <x-slot:activity><x-wirekit::text>Activity panel.</x-wirekit::text></x-slot:activity>
        <x-slot:settings><x-wirekit::text>Settings panel.</x-wirekit::text></x-slot:settings>
    </x-wirekit::tabs>
    <x-wirekit::text size="sm" variant="muted">Last event payload: <span x-text="last"></span></x-wirekit::text>
</x-wirekit::stack>
:::

From a Livewire component the same event is dispatched with `$this->dispatch('wirekit:tab-changed', name: 'activity')`.

## Two directions, and the difference matters first

Some events WireKit **dispatches** — you add a listener and react. Others WireKit **listens
for** — you dispatch them to drive a component. The tables below are the first kind. The
second kind is almost entirely the overlay vocabulary (`wirekit-modal-show`,
`wirekit-drawer-close`, `wirekit-alert-dialog-close` and their siblings), and it lives in
[Overlay Events](/overlays/events) with the payload each one expects.

If you are looking for "how do I open a modal from Livewire", that is the other page.

## The full inventory of what WireKit dispatches

### On the convention

These use the namespace and the colon, and they are the shape new events will take.

| Event | Dispatched by |
|---|---|
| `wirekit:image-compare-slide` | image-compare |
| `wirekit:inline-edit-confirmed` | inline-edit |
| `wirekit:inline-edit-opened` | inline-edit |
| `wirekit:otp-complete` | otp-input |
| `wirekit:rail:toggled` | app-rail |
| `wirekit:reading-progress:milestone` | reading-progress |
| `wirekit:reading-spine:section-changed` | reading-spine |
| `wirekit:replayed` | replay-button |
| `wirekit:reveal` | animate, reveal |
| `wirekit:sidebar:toggled` | sidebar-rail |
| `wirekit:sortable:reordered` | sortable |
| `wirekit:tab-changed` | tabs |
| `wirekit:theme-changed` | theme-controller |

### Namespaced with a hyphen

Older, and every one of them keeps working unchanged for the whole of v2 — the names below are
the contract. They are listed apart because a new event will not be named this way.

| Event | Dispatched by |
|---|---|
| `wirekit-command-palette-query` | command-palette |
| `wirekit-countdown-expired` | countdown |
| `wirekit-overlay-stack-changed` | the overlay stack |
| `wirekit-stream-event` | stream |
| `wirekit-toast` | toast |
| `wirekit-toast-{name}` | toast, scoped to one region |

`wirekit-toast-{name}` is assembled at runtime from the region's name, so it is the one entry
here that no static scan of this repository can confirm — worth knowing if you ever grep for it
and come up empty.

### Without a namespace

::: warning
These ten carry no prefix at all, and three of them — `selection-change`, `sort-change`,
`view-change` — are generic enough to collide with an event from your own application or another
library. A collision here fails silently: both listeners run, and the wrong one may act on a
payload it did not expect. Do not listen for these on `window`; scope the listener to the
component's own element.
:::

| Event | Dispatched by |
|---|---|
| `cell-change` | status-matrix |
| `conversation-reached-top` | conversation |
| `event-click` | event-calendar |
| `filter-change` | filter-builder |
| `marker-click` | map |
| `search-change` | data-table, filter-builder |
| `selection-change` | data-table |
| `sort-change` | data-table |
| `tree-node-select` | tree-view |
| `view-change` | event-calendar |

They keep working for the whole of v2. Renaming them is a breaking change and belongs to a major
version, alongside an alias period — not to a tidy-up.

## What this means for your code

- **Listening is safe.** Every name on this page is stable for v2.
- **Prefer scoping to the element** over `window` for the unprefixed ten, because those are the
  ones that can collide.
- **Writing your own component?** Use `wirekit:`-style names only for events you dispatch from
  WireKit components. Your own components should carry your own namespace, for exactly the
  reason this page exists.