AlpineJS Skill: Custom Events with $dispatch()

$dispatch('eventName', detailObject)

This is the core AlpineJS magic variable (function) used to send out a custom event.

• 'eventName': A string that uniquely identifies your custom event. Use descriptive, kebab-case names (e.g., 'cart-updated', 'item-selected').
• detailObject (optional): A JavaScript object containing any data you want to send along with the event. This is often referred to as the event's "payload" or "detail."

  // Example: Dispatching an event with a payload
  this.$dispatch('user-preference-changed', { theme: 'dark', fontSize: 16 });

@event-name.modifier="handler($event.detail)" or x-on:event-name.modifier="handler($event.detail)"

This is Alpine's directive for listening to DOM events, including custom ones you dispatch.

• @event-name: Replace event-name with the actual name of the custom event you're listening for (e.g., @user-preference-changed).
• .modifier (optional but often crucial): Modifiers change how the event listener behaves. The most important one for inter-component communication is .window. Others include .document, .self, .once, .prevent, .stop.
• "handler($event.detail)": The JavaScript expression or component method to execute when the event is caught.
  • $event: The native browser Event object (or more specifically, a CustomEvent for dispatched events).
  • $event.detail: This is where the detailObject (payload) sent with $dispatch() is accessible. This is a standard convention for custom events.

    <!-- Example: Listening for the event -->
    <div @user-preference-changed.window="applyPreferences($event.detail)">...</div>
    
    <script>
      // In an Alpine component
      // applyPreferences(detail) { /* 'detail' here is the { theme: 'dark', ... } object */ }
    </script>

.window modifier

When you use @event-name.window, the event listener is attached to the global window object instead of the DOM element where the directive is placed. This is essential for:

• Listening to events dispatched by components that are not direct descendants or ancestors (e.g., sibling components).
• Creating "global" event listeners that can react to events from anywhere in the application.

Without .window (or .document), a dispatched event only "bubbles up" the DOM tree from the element that dispatched it. If a listening component is not in this upward path, it won't receive the event.

Using the .window modifier is crucial for global events or when the listening component is not a direct ancestor of the dispatching component.

Python developers might be used to signal/slot systems or pub/sub patterns that are inherently global or managed by a central dispatcher. In the browser DOM, event propagation is more structured. By default, $dispatch() creates an event that bubbles up. If Component X dispatches 'my-event', and Component Y (a sibling or unrelated component) wants to listen, Component Y must use @my-event.window="handler". If Component Y is a direct parent of X, then @my-event="handler" on Y would suffice, but .window is safer for truly decoupled patterns.

Event detail ($event.detail) is where the payload sent with $dispatch is found.

It's a common point of confusion for beginners. They might instinctively look for the payload directly on $event (e.g., $event.data or $event.payload). However, the standard for custom events (which AlpineJS adheres to) places the payload in the detail property of the event object. So, if you dispatch an event like this.$dispatch('item-added', { id: 1, name: 'New Item' }), the listener must access it via $event.detail.id and $event.detail.name.