Docs

Docs

Event Handling

Handling events in a Hilla application. Event listener props and event objects in React views.

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

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

Registering Event Listeners

To register an event listener in a React view, pass a function as a prop named after the event. In the example below, the view registers the sayHello() function to show a notification when the user clicks the button.

Open in a
new tab
Source code
click-view.tsx

Vaadin React components accept a listener prop for each event that the underlying web component dispatches. The prop is the camel-cased event name prefixed with on, so a value-changed event is handled with an onValueChanged prop, and a selected-items-changed event with an onSelectedItemsChanged prop.

Note
Event handling in Lit views
Lit views bind listeners in the template instead, with @event bindings such as @click="${this.sayHello}". See the Lit Events documentation for details, and Creating Components for the binding syntax.

Available Event Types

The most-often-used events in Hilla 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 comprehensive lists of the events available for all HTML elements in the Element and HTML element API references.

Web components, and hence Vaadin components, also dispatch custom events. See the API references for these in the Vaadin components documentation.

Event Object

The listener functions 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: a reference to the target (element) of the interaction

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

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

Vaadin React components export a type for each of their events, so that the listener argument can be typed. In the example below, the value-changed event of a TextField is typed as TextFieldValueChangedEvent, and event.detail.value is used to read the edited value:

Open in a
new tab
Source code
value-changed-view.tsx
Note
React synthetic events

For the built-in events of plain HTML elements, React passes its own synthetic event object to the listener, and the browser event is available as event.nativeEvent. The custom events of Vaadin React components are passed to the listener as they are.

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

User Input in Forms

When creating forms in Hilla applications, consider using the Form Binder. With the form binder, you can avoid writing code to handle change events in the form, since the binder automatically tracks those changes.

Application State

Developers often need to keep state consistent across a view or the entire application. See Full-Stack Signals for state that’s shared with the server, and the React state documentation for state that’s local to the browser.

Updated –