Event handlers

Event handlers allow you to trigger queries, control components, and perform other actions in response to user interactions, all without writing custom JavaScript.

You can add event handlers in response to component events—similar to addEventListener events in native JavaScript and onChange events in React—or in response to queries. For example, you can create an event handler to trigger a query in response to a button click, or in response to a successful table update.

Use in response to component events

Create event handlers in response to component events in the Interaction section of the Inspector by clicking + Add next to Event handlers.

The available events depend on the attached component. For example, Text input components have Submit, Change, Focus, and Blur events, while Button components only have a Click event. The component library contains a full reference of these events.

Multiple event handlers

You can add multiple event handlers to a single component, but note that they run in parallel. In the following example, the event handlers calling getUsers and sendEmail are triggered at the same time.

Multiple async event handlers

To chain event handlers synchronously, create event handlers in response to query successes or failures.

Use in response to queries

Create events in response to queries by adding the event handler to the Success or Failure section of the query editor.

Event handlers set on a query's success or failure are chained and run synchronously.

For example, the below refreshUserData query runs only after the insertNewRow query returns a success response.

On success event handler

Event handler actions

The following are actions an event handler can take. Actions can be set in the Action dropdown when creating or editing an event handler.

ActionDescription
Control queryTrigger, reset, or clear the cache for a query.
Control componentsChoose a component and call one of its methods. View component events and methods in the component library.
Run scriptRun a JavaScript script.
Go to appNavigate with optional query or hash parameters to a Retool app.
Go to URLNavigate with optional query or hash parameters to an external URL.
Show notificationShow an informational, success, warning, or error message.
Set temporary stateStore any data in temporary state, similar to a global variable in JavaScript.
Set local storageSet or clear data in local storage.
Copy to clipboardCopy a value to the user's clipboard.
Export dataExport data to a CSV, TSV, JSON, or Excel (.xlsx) file.
ConfettiShow confetti animation.

Control component details

After selecting the Control components action, choose a component to see its available methods. The definitions for these methods can be found in the component library under the Methods heading of a given component. You can use any component API in event handlers.

For example, the following switch event handler uses the table's .setFilter() method to filter by active users.

Set filters on table from event handler

Duplicate or delete event handlers

To duplicate an event handler to the same component or query, click ... to the right of the event handler, then Duplicate.

To delete an event handler, click ... to the right of the event handler, then Delete.

Duplicate or delete event handler

Conditional runs

Use the Only run when option to configure event handlers to only run when a given condition evaluates to true.

For example, the following event handler controls a Form that either edits or creates a user, depending on whether a row is selected.

Only run when event handler options

The first Trigger query event handler runs createNewUser only when there is no row selected, and therefore ID is falsey: {{ !id }}.

The second Trigger query event handler runs editUser only when an user ID exists: {{ !!id }}.

Debounce and throttle

Debounce and throttle settings modify the timing of an event handler.

Debounce or throttle event handlers

Debounce

Debounce delays an action until the specified milliseconds have elapsed since the event was last triggered. It's useful for delaying expensive queries.

For example, a text input which updates on every user input might use an expensive underlying query. Instead of calling this query on every keystroke, use Debounce to run the query only when the user stops typing.

Throttle

Setting a Throttle ensures an action is only called once per the specified milliseconds.

For example, a button might use an event handler to call an expensive refreshUserData query on click. Use Throttle on the event handler so the query runs at most every two seconds, even if a user clicks the button more frequently.