# How to Use Keyboard Shortcuts in Retool

- Tool: Retool
- Difficulty: Beginner
- Time required: 10-15 min
- Compatibility: Retool Cloud and Self-hosted
- Last updated: March 2026

## TL;DR

Retool has two sets of shortcuts: editor shortcuts for builders (Cmd+S save, Cmd+Z undo, Cmd+Enter run query) and configurable end-user shortcuts on component event handlers. Configure end-user shortcuts by adding a 'Key press' event handler in Inspector → Interaction, specifying the key combination, and setting the action to trigger.

## Editor Shortcuts and Custom End-User Keyboard Shortcuts in Retool

Retool has two categories of keyboard shortcuts that serve different purposes. Editor shortcuts help builders develop apps faster — they work only in Retool's edit mode. End-user shortcuts are configured by builders and available to app users in Preview/Published mode.

Editor shortcuts are fixed and cannot be customized. The most important ones: Cmd+S (or Ctrl+S on Windows) saves the app, Cmd+Z undoes the last canvas change, Cmd+Enter runs the currently selected query, Ctrl+Shift+P (or Cmd+Shift+P) previews the app, and Cmd+K opens the command palette. A full reference is available in Retool's documentation and via the command palette.

End-user shortcuts are configured per component via the 'Key press' event type in the Inspector's Event Handlers section. A builder specifies a key combination (e.g., Enter, Cmd+K, Shift+S) and what action to take when it is pressed. This is how you make Enter submit a form, Escape close a modal, or a custom shortcut trigger a search.

## Before you start

- A Retool app in edit mode
- Basic familiarity with the Inspector panel and event handlers

## Step-by-step guide

### 1. Learn the essential editor shortcuts for faster building

Retool editor shortcuts work in the app editor (edit mode) only. The most-used shortcuts that every Retool builder should know: Cmd+S saves the app, Cmd+Z undoes canvas changes, Cmd+Y or Cmd+Shift+Z redoes, Cmd+Enter runs the currently focused query, Ctrl+Shift+P (Mac: Cmd+Shift+P) switches to Preview mode, Cmd+K opens the command palette (90+ actions), and Delete or Backspace removes the selected component.

```
// Essential editor shortcuts (Mac / Windows):
// Save app:             Cmd+S        / Ctrl+S
// Undo canvas change:   Cmd+Z        / Ctrl+Z
// Redo:                 Cmd+Shift+Z  / Ctrl+Y
// Run selected query:   Cmd+Enter    / Ctrl+Enter
// Preview app:          Cmd+Shift+P  / Ctrl+Shift+P
// Command palette:      Cmd+K        / Ctrl+K
// Delete component:     Backspace / Delete (when component selected)
// Duplicate component:  Cmd+D        / Ctrl+D
// Multi-select:         Shift+click
// Pan canvas:           Space + drag
// Zoom in/out:          Cmd+= / Cmd+- (or scroll with Cmd held)
```

**Expected result:** You can save, undo, run queries, and navigate the editor without reaching for the mouse.

### 2. Configure an Enter key shortcut to submit a form

The most common end-user keyboard shortcut is pressing Enter to submit a form. In Retool, this is configured by adding a 'Key press' event handler to a Text Input or Form component. Select the Text Input where the user types last before submitting. In Inspector → Interaction → Event Handlers, click '+ Add'. Set Event to 'Key press'. In the key field, enter 'Enter'. Set Action to 'Trigger query' → your submit query. Now pressing Enter in that Text Input triggers the submission.

```
// Text Input Inspector → Interaction → Event Handlers:
// Event: Key press
// Key: Enter
// Action: Trigger query → submitForm

// Add 'Only run when' condition to prevent submission while invalid:
// Only run when: {{ !form1.invalid }}

// For a search field — Enter triggers search:
// Event: Key press
// Key: Enter
// Action: Trigger query → searchRecords
```

**Expected result:** Pressing Enter in the Text Input triggers the submit query. The Disabled check prevents submission with invalid data.

### 3. Add an Escape key handler to close a modal

The Escape key conventionally closes dialogs. Add a Key press event handler to a Text Input or Button inside a Modal component. Set Key to 'Escape' and Action to 'Control component' → modal1 → close. Alternatively, add the handler to any component that has keyboard focus while the modal is open.

```
// Event handler on any input inside the modal:
// Event: Key press
// Key: Escape
// Action: Control component → modal1 → close

// To also reset the form when escaping:
// Add a second handler:
// Event: Key press
// Key: Escape
// Action: Control component → form1 → reset

// Note: Event handlers on the same event run in parallel
// If you need sequential close then reset, use a JS Query:
// Key press → Escape → Trigger query → closeAndResetModal

// JS Query: closeAndResetModal
form1.reset();
modal1.close();
```

**Expected result:** Pressing Escape while the modal is open closes it. If you added the reset handler, the form also clears.

### 4. Configure a custom shortcut for a global action

For global shortcuts that should work anywhere in the app (not just inside a specific component), add the Key press event handler to a component that always has focus, such as a search input or a dedicated invisible Button component. Place a Button named keyboardFocusTrap at the top of the canvas with width 0 and height 0, give it auto-focus via a 'Run on page load' JS Query that calls keyboardFocusTrap.focus(), and add your global keyboard shortcuts as Key press handlers on it.

```
// JS Query: setInitialFocus (Run on page load: ON)
// Sets focus to the global shortcut catcher button
keyboardFocusTrap.focus();

// keyboardFocusTrap Button event handlers:
// Event: Key press, Key: Ctrl+N / Cmd+N
// Action: Control component → createModal → open

// Event: Key press, Key: Ctrl+F / Cmd+F
// Action: Control component → searchInput → focus

// Event: Key press, Key: Escape
// Action: Trigger query → closeAllModals

// Note: Cmd+F is captured by the browser's Find function — 
// use Ctrl+Shift+F or another combination to avoid browser conflicts
```

**Expected result:** Global keyboard shortcuts work regardless of which component has focus, as long as the focus trap button retains focus.

### 5. Understand limitations of keyboard shortcuts in Custom Components

Custom Components in Retool are rendered inside an iframe sandbox. Keyboard events inside a Custom Component are captured by the iframe and do not bubble up to the Retool app's event handler system. This means Key press event handlers configured on Retool components do not fire when the keyboard focus is inside a Custom Component. Shortcuts also do not work inside embedded iframes or the JSON Explorer component.

```
// Known limitation: keyboard shortcuts in Custom Components
// Key press events on Retool components are NOT fired when:
// - Keyboard focus is inside a Custom Component (iframe)
// - Keyboard focus is inside an embedded URL iframe
// - The app is inside an iframe embed (external website)

// Workaround for Custom Component shortcuts:
// Handle keyboard events inside the Custom Component itself
// using document.addEventListener('keydown', ...) in the component code
// and communicate back to Retool via Retool.modelUpdate()

// Example Custom Component keyboard handler:
document.addEventListener('keydown', function(event) {
  if (event.key === 'Enter' && !event.isComposing) {
    Retool.modelUpdate({ enterPressed: true });
  }
});

// Then in Retool, add a 'modelUpdate' event handler on the Custom Component
// that triggers the desired action when enterPressed is true
```

**Expected result:** You are aware of the iframe limitation and use the Retool.modelUpdate() workaround for keyboard shortcuts inside Custom Components.

## Complete code example

File: `JS Query: handleGlobalShortcuts`

```javascript
// Reference: Common end-user keyboard shortcuts to configure
// Add these as Key press event handlers in Inspector → Interaction

// === FORM SHORTCUTS ===
// On any Text Input:
// Enter → Trigger query: submitForm (Only run when: {{ !form1.invalid }})
// Escape → Control component: form1 → reset

// === MODAL SHORTCUTS ===
// On Button inside modal:
// Escape → Control component: editModal → close
// Enter → Trigger query: saveRecord

// === SEARCH SHORTCUTS ===
// On searchInput Text Input:
// Enter → Trigger query: runSearch
// Escape → JS Query: clearAndBlurSearch

// JS Query: clearAndBlurSearch
await searchInput.setValue('');
searchInput.blur();

// === NAVIGATION SHORTCUTS ===
// On a focused Button (keyboardFocusTrap):
// Ctrl+N → Control component: createModal → open
// Ctrl+Shift+R → Trigger query: refreshAllData

// JS Query: refreshAllData
await Promise.all([
  getCustomers.trigger(),
  getOrders.trigger(),
  getStats.trigger(),
]);

utils.showNotification({
  title: 'Data refreshed',
  notificationType: 'success',
});
```

## Common mistakes

- **Testing keyboard shortcuts while in edit mode — the editor's own shortcuts (Cmd+S to save) intercept before the component's Key press handler fires** — undefined Fix: Always test end-user keyboard shortcuts in Preview mode (Ctrl+Shift+P) where editor shortcuts are inactive.
- **Adding multiple event handlers for the same Key press event and expecting them to run in sequence — they run in parallel** — undefined Fix: For sequential operations (close modal then reset form), combine all actions in a single JS Query and trigger it from the Key press event handler.
- **Expecting Key press handlers on a Retool component to fire when focus is inside a Custom Component or iframe** — undefined Fix: Key events inside iframes (Custom Components, embedded URLs) do not propagate to Retool. Handle keyboard shortcuts inside the Custom Component code and communicate via Retool.modelUpdate().
- **Configuring Cmd+F as a custom shortcut — browsers intercept this before Retool can handle it** — undefined Fix: Use Cmd+Shift+F or another non-reserved combination. Check browser keyboard shortcut documentation for your target browsers to avoid conflicts.

## Best practices

- Use Enter for form submission and Escape for cancel/close — these are universal conventions that users expect without any documentation
- Avoid overriding browser shortcuts (Cmd+F, Cmd+T, Cmd+W, Cmd+S) — use Cmd+Shift or Ctrl+Shift combinations for app-specific shortcuts
- Document custom keyboard shortcuts in the app's help text or a keyboard shortcuts modal — users cannot discover custom shortcuts without guidance
- Add 'Only run when' conditions to keyboard-triggered queries to prevent accidental submissions when validation fails
- Test keyboard shortcuts in Preview mode, not Edit mode — some editor shortcuts (Cmd+S, Cmd+Z) interfere with testing end-user shortcuts in edit mode
- For shortcuts that need to work app-wide, use a focus trap component rather than adding the same handler to every input
- Remember that event handlers on the same event run in parallel — use a JS Query for sequential ordered operations triggered by a single keypress

## Frequently asked questions

### Is there a list of all keyboard shortcuts available in the Retool editor?

Yes — open the command palette with Cmd+K (Ctrl+K on Windows) and look for 'Keyboard shortcuts' or 'Shortcuts reference' in the search. Retool also shows keyboard shortcut hints next to actions in context menus and the command palette results. The most complete reference is Retool's official documentation under the Editor section.

### Can I disable Retool editor keyboard shortcuts to prevent them from interfering with my custom shortcuts?

No — editor shortcuts cannot be disabled or remapped in Retool's current editor. To test end-user shortcuts without interference, always use Preview mode. Published apps delivered to users also do not have editor shortcuts active.

### Can I show users which keyboard shortcuts are available in my app?

Yes — build a keyboard shortcuts reference modal that lists your custom shortcuts. Add a '?' Key press event handler or a Keyboard Shortcuts button that opens a Modal containing a Table or list of available shortcuts. This is the standard pattern for apps with non-obvious keyboard interactions.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-use-keyboard-shortcuts-in-retool
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-use-keyboard-shortcuts-in-retool