Docs

Docs

Handling Events

Events are dispatched in the browser when the user interacts with the interface. Web applications can react on those interactions by handling events, for example, running some code when the user clicks a certain button.

To handle events, applications register event listener methods for specific event types (which denote the type of interaction, such as click) on the interactive targets (typically interface elements).

Declarative Event Listeners

For registering event listeners in Fusion application views, declare them in your Lit templates using @event bindings with view class methods. In the example below, the view registers an event listener for the sayHello method to show the notification when the user clicks the button.

Open in a
new tab
@customElement('click-view')
export class ClickView extends LitElement {
  render() {
    return html`<vaadin-button @click="${this.sayHello}">Say hello</vaadin-button>`;
  }

  private sayHello() {
    Notification.show('Hello');
  }
}

You can also add event listeners programmatically when needed, as well as dispatch and listen for custom events. See the Lit Events documentation for those use cases and examples.

Events Available for Handling

The most often used events in Fusion applications fall into two major categories: built-in and custom ones.

The built-in events, such as click, input, and change, are dispatched by the browser itself, and are typically available on every element. You can find the comprehensive lists of events available for all HTML elements in the Element API and the HTMLElement API References.

Web components, and Vaadin components as such, also dispatch custom events. See the API references for those in the Vaadin components documentation.

Event Object

The listener methods receive the event object as the first argument. The event objects provide some useful properties and methods, such as:

  • event.type the event type string, for example, click

  • event.target the reference to the target (element) of the interaction

  • event.detail in CustomEvent types, which is often used by web components for event-specific data, for example, event.detail.value is often used to propagate the new value in property-changed events and such

  • event.preventDefault() to cancel the built-in handling of the particular event, for example, to prevent the browser from navigating when the user clicks a link, after that click was already handled in the listener

In the example below, the event.detail.value is used in the value-changed event handler to extract the edited value property of the <vaadin-text-field> element:

Open in a
new tab
@customElement('value-changed-view')
export class ValueChangedView extends LitElement {
  @state()
  private name = '';

  render() {
    return html`
      <vaadin-text-field label="Your name" @value-changed="${this.nameChanged}"></vaadin-text-field>
      <div>Your name is: ${this.name}</div>
    `;
  }

  private nameChanged(event: CustomEvent) {
    this.name = event.detail.value;
  }
}

Some common use cases of event handling are also explained in other articles.

User Input in Forms

When making forms in Fusion applications, consider using the Form Binder. With the form binder, you could avoid writing code for handling change events in the form, since the binder automatically tracks those changes.

View Properties

To maintain a consistent state within a view, it is a good idea to use declarative template bindings (.property="${this.value}") and avoid the imperative element.property = this.value; code style in event listeners. See the LitElement basics article for the binding syntax.

Application State

Often developers need to maintain the state consistent across the entire web application. To achieve that, consider using State Management.