x-on

x-on allows you to easily run code on dispatched DOM events.

Here's an example of simple button that shows an alert when clicked:

<button x-on:click="alert('Hello World!')">Say Hi</button>

Shorthand syntax

If x-on: is too verbose for your tastes, you can use the shorthand syntax: @.

Here's the same component as above, but using the shorthand syntax instead:

<button @click="alert('Hello World!')">Say Hi</button>

Keyboard events

Alpine makes it easy to listen for keydown and keyup events on specific keys.

Here's an example of listening for the Enter key inside an input element:

<input type="text" @keyup.enter="alert('Submitted!')">

You can also chain these key modifiers to achieve more complex listeners, such as when the Shift key is held and Enter is pressed:

<input type="text" @keyup.shift.enter="alert('Submitted!')">

You can directly use any valid key names exposed via KeyboardEvent.key as modifiers by converting them to kebab-case. For example:

<input type="text" @keyup.page-down="alert('Submitted!')">

For easy reference, here is a list of common keys:

Modifier	Keyboard Key
.shift	Shift
.enter	Enter
.space	Space
.ctrl	Ctrl
.cmd	Cmd
.meta	Cmd on Mac, Windows key on Windows
.alt	Alt
.up .dow	n .left .right Up/Down/Left/Right arrows
.escape	Escape
.tab	Tab
.caps-lo	ck Caps Lock
.equal	Equal, =
.period	Period, .
.comma	Comma, ,
.slash	Forward Slash, /

Mouse events

Similar to Keyboard Events, Alpine allows the use of some key modifiers for handling mouse events.

Modifier	Event Key
.shift	shiftKey
.ctrl	ctrlKey
.cmd	metaKey
.meta	metaKey
.alt	altKey

These work on click, auxclick, context and dblclick events, and even mouseover, mousemove, mouseenter, mouseleave, mouseout, mouseup and mousedown.

Here's an example of a button that changes behaviour when the Shift key is held down:

<button type="button"
    @click="message = 'selected'"
    @click.shift="message = 'added to selection'">
    @mousemove.shift="message = 'add to selection'"
    @mouseout="message = 'select'"
    x-text="message"></button>

Custom events

Alpine event listeners are a wrapper for native DOM event listeners. Therefore, they can listen for ANY DOM event, including custom events.

Here's an example of a component that dispatches a custom DOM event and listens for it as well:

<div x-data @foo="alert('Button Was Clicked!')">
    <button @click="$event.target.dispatchEvent(new CustomEvent('foo', { bubbles: true }))">...</button>
</div>

When the button is clicked, the @foo listener will be called.

Modifiers

Alpine offers a number of directive modifiers to customize the behavior of your event listeners.

.prevent

.prevent is equivalent to calling .preventDefault() inside a listener on the browser event object.

<form @submit.prevent="console.log('submitted')" action="/foo">
    <button>Submit</button>
</form>

In the above example, with the .prevent, clicking the button will NOT submit the form to the /foo endpoint. Instead, Alpine's listener will handle it and "prevent" the event from being handled any further.

.stop

.stop is equivalent to calling .stopPropagation() inside a listener on the browser event object.

<div @click="console.log('I will not get logged')">
    <button @click.stop>Click Me</button>
</div>

In the above example, clicking the button WON'T log the message. This is because we are stopping the propagation of the event immediately and not allowing it to "bubble" up to the <div> with the @click listener on it.

.outside

.outside is a helper that listens for clicks outside the element it's attached to.

<div x-data="{ open: false }">
    <button @click="open = ! open">Toggle</button>
    <div x-show="open" @click.outside="open = false">
        Contents...
    </div>
</div>

In the above example, after showing the dropdown contents by clicking the "Toggle" button, you can close the dropdown by clicking anywhere on the page outside the content.

NOTE

It's worth noting that the .outside expression will only be evaluated when the element it's registered on is visible on the page. Otherwise, there would be nasty race conditions where clicking the "Toggle" button would also fire the @click.outside handler when it is not visible.

.window

When the .window modifier is present, Alpine will register the event listener on the root window object on the page instead of the element itself.

<div @keyup.escape.window="...">...</div>

The above snippet will listen for the "escape" key to be pressed ANYWHERE on the page.

Adding .window to listeners is extremely useful for these sorts of cases where a small part of your markup is concerned with events that take place on the entire page.

.document

.document works similarly to .window only it registers listeners on the document global, instead of the window global.

.once

By adding .once to a listener, you are ensuring that the handler is only called ONCE.

<button @click.once="console.log('I will only log once')">...</button>

.debounce

NOTE

Debounce is a technique used in programming to delay the execution of a function until after a certain period of inactivity.

Sometimes, it's helpful to "debounce" an event handler so it's only called after a short delay (250 milliseconds by default). For instance, in a search field that triggers network requests as the user types, debouncing stops the requests from firing after every keystroke.

<input @input.debounce="fetchResults">

To change the delay duration, add a duration after .debounce:

<input @input.debounce.500ms="fetchResults">

.throttle

.throttle is similar to .debounce, but instead of waiting for inactivity, it triggers the function every 250 milliseconds by default. This is useful when events are repeated continuously, and you still want to handle them at regular intervals.

One of the good exampls for this is highlighting a sidebar section as you scroll through a page.

<div @scroll.window.throttle="handleScroll">...</div>

Without .throttle, the handleScroll method would be fired hundreds of times as the user scrolls down a page. This can really slow down a site.

Similar to .debounce, you can also change the duration to your throttled event:

<div @scroll.window.throttle.750ms="handleScroll">...</div>

.self

Adding .self to an event listener ensures the event is triggered only when it originates from the element itself, and not from its child elements.

<button @click.self="handleClick">
    Click Me
    <img src="...">
</button>

In the above example, normally any click originating within the <button> element (like on <img> for example), would be picked up by a @click listener on the button. However, in this case, because we've added a .self, only clicking the button itself will call handleClick. Only clicks originating on the <img> element will not be handled.

.camel

x-on can only listen for events with lower case names, as HTML attributes are case-insensitive. So, writing x-on:CLICK will listen for an event named click. If you need to listen for a custom event with a camelCase name, you can use the .camel helper to work around this limitation.

<div @custom-event.camel="handleCustomEvent">
    ...
</div>

By adding .camel in the above example, Alpine is now listening for customEvent instead of custom-event.

.dot

Similar to the .camelCase modifier there may be situations where you want to listen for events that have dots in their name (like custom.event). Since dots within the event name are reserved by Alpine you need to write them with dashes and add the .dot modifier.

<div @custom-event.dot="handleCustomEvent">
    ...
</div>

In the code example above custom-event.dot will correspond to the event name custom.event.

.passive

Browsers optimize scrolling on pages to be fast and smooth even when JavaScript is being executed on the page. However, improperly implemented touch and wheel listeners can block this optimization and cause poor site performance.

If you are listening for touch events, it's important to add .passive to your listeners to not block scroll performance.

<div @touchstart.passive="...">...</div>

.capture

Add this modifier if you want to execute this listener in the event's capturing phase, e.g. before the event bubbles from the target element up the DOM.

<div @click.capture="console.log('I will log first')">
    <button @click="console.log('I will log second')"></button>
</div>

Without .capture, when you click the parent element button:

• First, buttonClick is triggered.
• Then, parentClick is triggered (because the event "bubbles up").

But with .capture, when you click the button:

• First, parentClick is triggered (during the capturing phase, as the event moves down).
• Then, buttonClick is triggered.