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:

   {
       "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:

   addHotkey('app', 'myAction', ['mod+k']); // Default binding
   

3. Use the Hotkey in Components

   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:

  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:

  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:

  addHotkey('canvas', 'redo', ['mod+shift+z', 'mod+y']); // Two alternatives