---
name: "[up-emit]"
area: "API"
kind: "HTML attribute"
parent: "up.event module"
url: "https://unpoly.com/api/up-emit"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [up.event module](https://unpoly.com/api/up.event.md)</nav>

# [up-emit]

Emits a custom event when this element is clicked.

The event is emitted on this element and bubbles up to the `document`. To listen to the event, use [`addEventListener()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) or [`up.on()`](https://unpoly.com/api/up.on.md) 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 it to non-interactive elements, like a `<span>`.

<nav aria-label="Guides">

- [Learn: Elements that act like links or buttons](https://unpoly.com/learn/faux-interactive-elements.md)

</nav>

<nav aria-label="Contents">

#### Contents

- [Example](#example)
- [Event properties](#event-properties)
- [Fallback URLs](#fallback)
- [Modifying attributes](#attributes)

</nav>

## Example {#example}

This button will emit a `user:select` event when pressed:

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

The event can be handled by a listener:

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

## Event properties {#event-properties}

By default `[up-emit]` will emit an event with only basic properties like [`{ target }`](https://developer.mozilla.org/en-US/docs/Web/API/Event/target).

To set custom properties on the event object, encode them as [relaxed JSON](https://unpoly.com/api/relaxed-json.md) in an `[up-emit-props]` attribute:

```html
<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 {#fallback}

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

```html
<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:

```js
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](https://unpoly.com/api/up-follow.md) to the `/menu` path.

> #### Tip
>
> When an [event closes an overlay](https://unpoly.com/learn/subinteractions.md#event-condition) 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](https://unpoly.com/api/up.layer.root.md).

---

## Modifying attributes {#attributes}

### up-emit {#up-emit}

(required)

The [type](https://developer.mozilla.org/en-US/docs/Web/API/Event/type) of the event to be emitted, e.g. `my:event`.

### [up-emit-props='{}'] {#up-emit-props}

(optional)

The event properties, serialized as [relaxed JSON](https://unpoly.com/api/relaxed-json.md).