up.event [up-emit]

HTML selector

Emits a custom event when this element is clicked.

The event is emitted on this element and bubbles up the document. To listen to the event, use addEventListener() or up.on() on the element, or on its ancestors.

While the [up-emit] attribute is often used with an <a> or <button> element, you can also apply to to non-interactive elements, like a <span>. See clicking on non-interactive elements for details and accessibility considerations.

Example

This button will emit a menu:open event when pressed:

<button type="button" up-emit='user:select'>Alice</button>

The event can be handled by a listener:

document.addEventListener('user:select', function(event) {
  up.reload('#user-details')
})

Event properties

By default [up-emit] will emit an event with only basic properties like { target }.

To set custom properties on the event object, encode them as relaxed JSON in an [up-emit-props] attribute:

<button type="button"
  up-emit="user:select"
  up-emit-props="{ id: 5, firstName: 'Alice' }">
  Alice
</button>

<script>
  up.on('user:select', function(event) {
    console.log(event.id)        // logs 5
    console.log(event.firstName) // logs "Alice"
  })
</script>

Fallback URLs

Use [up-emit] on a link to define a fallback URL that is rendered in case no listener handles the event:

<a href="/menu" up-emit='menu:open'>Menu</a>

When a listener has handled the menu:open event, it should call event.preventDefault(). This also prevents the original click event, causing the link to no longer be followed:

document.addEventListener('menu:open', function(event) {
  event.preventDefault() // prevent the link from being followed
})

If no listener prevents the menu:open event, the browser will navigate to the /menu path.

Tip

When an event closes an overlay via [up-accept-event] or [up-dismiss-event], its default is prevented. You can use fallback URLs to make a link that emits a closing event in an overlay, but navigates to a different page on the root layer.