# Hotkeys

InvokeAI allows you to customize all keyboard shortcuts (hotkeys) to match your workflow preferences. This guide covers how to use and customize hotkeys as a user, as well as providing technical documentation for developers.

## User Guide

### View All Hotkeys

See all available keyboard shortcuts organized by category in one place.

### Customize Any Hotkey

Change any shortcut to your preference, or assign multiple key combinations to the same action.

### Smart Validation

Built-in validation prevents invalid combinations.

### Persistent Settings

Your custom hotkeys are safely stored and restored across sessions.

### Opening the Hotkeys Modal

Press `Shift` \+ `?` or click the **keyboard icon** in the application to open the Hotkeys Modal.

### Managing Hotkeys

- Browse all available hotkeys organized by category (App, Canvas, Gallery, Workflows, etc.).
- Search for specific hotkeys using the search bar.
- See the current key combination for each action.

1. Click the **pencil** button by the hotkey you want to change, or click the **plus** button to add a new one.
2. Enter your new hotkey combination in the editor.
   - Use modifier buttons for quick-insert ( `Mod`, `Ctrl`, `Shift`, `Alt`).
   - Check the live preview to see how your hotkey will look.
3. Click the **checkmark** or press `Enter` to save.

- **Reset a single hotkey:** Click the counter-clockwise arrow icon next to customized hotkeys.
- **Reset all hotkeys:** In Edit Mode, click the **Reset All to Default** button at the bottom.

### Hotkey Format Reference

When customizing hotkeys, use the following formats:

- **Valid Modifiers:**`mod` (Ctrl on Windows/Linux, Cmd on Mac), `ctrl`, `shift`, `alt`
- **Valid Keys:** Letters (`a-z`), Numbers (`0-9`), Function keys (`f1-f12`), Special keys (`enter`, `space`, `tab`, `backspace`, `delete`, `escape`), Arrow keys (`up`, `down`, `left`, `right`)
- **Multiple alternatives:** Separate with commas (e.g., `mod+enter, ctrl+enter`)

* * *

## Developer Guide

The hotkeys system allows developers to centrally define, manage, and validate hotkeys throughout the application. It is built on top of `react-hotkeys-hook`.

### Architecture

The customizable hotkeys feature comprises the following components:

- **Hotkeys State Slice (`hotkeysSlice.ts`)**: Stores custom hotkey mappings in Redux state. Persisted to IndexedDB using `redux-remember`.
- **`useHotkeyData` Hook (`useHotkeyData.ts`)**: Defines all default hotkeys and merges them with custom hotkeys from the store.
- **`HotkeyEditor.tsx`**: Inline editor with live preview, validation, and modifier insertion.
- **`HotkeysModal.tsx`**: The modal interface supporting View/Edit modes, searching, and categories.

### Adding New Hotkeys

To add a new hotkey to the system, follow these steps:

1. **Add Translation Strings**  
   In `invokeai/frontend/web/public/locales/en.json`:
   
   ```json
   {
       "hotkeys": {
           "app": {
               "myAction": {
                   "title": "My Action",
                   "desc": "Description of what this hotkey does"
               }
           }
       }
   }
   ```

2. **Register the Hotkey**  
   In `invokeai/frontend/web/src/features/system/components/HotkeysModal/useHotkeyData.ts`:
   
   ```javascript
   addHotkey('app', 'myAction', ['mod+k']); // Default binding
   ```

3. **Use the Hotkey in Components**  
   
   ```javascript
   import { useRegisteredHotkeys } from 'features/system/components/HotkeysModal/useHotkeyData';
   
   const MyComponent = () => {
       const handleAction = useCallback(() => {
           // Your action here
       }, []);
       useRegisteredHotkeys({
           id: 'myAction',
           category: 'app',
           callback: handleAction,
           options: { enabled: true, preventDefault: true },
           dependencies: [handleAction]
       });
       // ...
   };
   ```

### Common Patterns

- **Conditional Hotkeys**  
   Only enable hotkeys when certain conditions are met:
   
   ```javascript
   useRegisteredHotkeys({
       id: 'save',
       category: 'app',
       callback: handleSave,
       options: {
           enabled: hasUnsavedChanges && !isLoading, // Only when valid
           preventDefault: true
       },
       dependencies: [hasUnsavedChanges, isLoading, handleSave]
   });
   ```

- **Focus-Scoped Hotkeys**  
   Ensure hotkeys are only active when a specific region is focused:
   
   ```javascript
   import { useFocusRegion } from 'common/hooks/focus';
   const MyComponent = () => {
       const focusRegionRef = useFocusRegion('myRegion');
       useRegisteredHotkeys({
           id: 'myAction',
           category: 'app',
           callback: handleAction,
           options: { enabled: true }
       });
       return <div ref={focusRegionRef}>...</div>;
   };
   ```

- **Multiple Alternatives**  
   Provide multiple alternatives for the same action:
   
   ```javascript
   addHotkey('canvas', 'redo', ['mod+shift+z', 'mod+y']); // Two alternatives
   ```