How to Use Event Handlers in Retool

Select a Button component on the canvas. In the Inspector panel on the right, scroll to the Interaction section. You will see an 'Event handlers' area with a + button. Click + to add a new handler. In the handler configuration, choose the Event (onClick for buttons), then choose the Action. The most common actions are: Trigger query, Control component (open/close modal), Set variable, Navigate to page, and Show notification.

In the event handler configuration, set Event to onClick and Action to Trigger query. Select the query name from the dropdown. Optionally set 'Only run when' to a {{ }} expression that must evaluate to true for the handler to fire (e.g., {{ table1.selectedRow.data !== undefined }}). You can also set 'Show success toast' and 'Show failure toast' options — these display automatic notifications without any JS code.

1// Handler configuration (set via Inspector dropdowns):
2// Event: onClick
3// Action: Trigger query
4// Query: deleteRecord
5// Only run when: {{ table1.selectedRow.data !== undefined }}
6
7// Optional: if you need additional params, use a JS Query instead:
8// Action: Run script
9// Script:
10await deleteRecord.trigger({
11  additionalScope: { id: table1.selectedRow.data.id }
12});

Queries themselves have event handlers for their success and failure states. Select a query in the Code panel. In the query's Settings, you will find Success event handlers and Failure event handlers. These fire after the query completes or fails. Use Success handlers to chain follow-up actions (e.g., refresh a table after an insert). Use Failure handlers to show error notifications or reset state.

1// Query: insertRecord
2// Success handler:
3//   Action: Trigger query → getRecords (refresh table)
4//   Action: Control component → modal1.close()
5//   Action: Show notification → 'Record created'
6
7// Failure handler:
8//   Action: Show notification → 'Insert failed: {{ insertRecord.error.message }}'

When you add multiple event handlers to the same event (e.g., two handlers on a Button's onClick), Retool fires them simultaneously — they run in parallel, not sequentially. This means if handler 1 runs updateRecord and handler 2 runs getRecords, getRecords may complete before updateRecord, returning stale data. To avoid this, either consolidate all logic into a single JS Query that uses await for sequential execution, or chain actions via query success handlers.

1// PROBLEM: Two onClick handlers run in parallel
2// Handler 1: Trigger query → updateRecord
3// Handler 2: Trigger query → getRecords
4// Result: getRecords may return BEFORE updateRecord finishes!
5
6// SOLUTION A: Use a single JS Query as the onClick handler
7// Handler 1: Run script
8await updateRecord.trigger();
9await getRecords.trigger(); // Guaranteed to run AFTER update
10
11// SOLUTION B: Chain via query success event
12// updateRecord → Success handler: Trigger query → getRecords
13// (getRecords runs only AFTER updateRecord succeeds)

Text Input and Select components expose an onChange event that fires every time the value changes. This is useful for real-time search and filter patterns. In the Inspector Interaction section, add an onChange handler that triggers a search query. Be aware that onChange fires on every keystroke for text inputs — if your query is expensive, consider using a debounce pattern via a JS Query instead.

1// Text Input: searchInput
2// onChange handler: Trigger query → searchCustomers
3
4// SQL Query: searchCustomers
5// SELECT * FROM customers
6// WHERE name ILIKE {{ '%' + searchInput.value + '%' }}
7// Run when inputs change: enabled
8
9// For debounced search (avoids query on every keystroke):
10// onChange handler: Run script
11clearTimeout(window._searchTimer);
12window._searchTimer = setTimeout(async () => {
13  await searchCustomers.trigger();
14}, 300); // 300ms debounce

In multipage apps, event handlers can navigate to other pages. Add an onClick handler and set Action to Navigate to. Choose the target page from the dropdown. You can pass URL parameters to the destination page by configuring query params. To pass complex data between pages, use global variables (global.setValue()) in a JS Query instead.

1// Simple navigation handler:
2// Event: onClick
3// Action: Navigate to
4// Page: CustomerDetail
5// URL params: { id: {{ table1.selectedRow.data.id }} }
6
7// Or use a JS Query for complex navigation with global variable:
8await global.setValue('selectedCustomerId', table1.selectedRow.data.id);
9await global.setValue('selectedCustomerName', table1.selectedRow.data.name);
10utils.openPage('CustomerDetail');