Configure event handlers
Learn how to trigger actions and queries in response to user interactions.
You can add event handlers in response to component events—similar to
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 + 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
sendEmail are triggered at the same time.
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
getData query runs only after the
insertNewRow query returns a success response.
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.
|Control query||Trigger, reset, or clear the cache for a query.|
|Control components||Choose a component and call one of its methods. View component events and methods in the component library.|
|Go to app||Navigate with optional query or hash parameters to a Retool app.|
|Go to URL||Navigate with optional query or hash parameters to an external URL.|
|Show notification||Show an informational, success, warning, or error message.|
|Set local storage||Set or clear data in local storage.|
|Copy to clipboard||Copy a value to the user's clipboard.|
|Export data||Export data to a CSV, TSV, JSON, or Excel (.xlsx) file.|
|Confetti||Show 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.
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.
Use the Only run when option to configure event handlers to only run when a given condition evaluates to
For example, the following event handler only runs the
Debounce and throttle
Debounce and throttle settings modify the timing of an event handler.
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.
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.
Updated about 1 month ago