JavaScript Commands and Keybindings

Summary

The Commands and Keybindings API allows extensions to register custom commands and associate them with keyboard shortcuts. This enables users to quickly trigger actions without using the mouse.

Basic Usage

app.registerExtension({
  name: "MyExtension",
  // Register commands
  commands: [
    {
      id: "myCommand",
      label: "My Command",
      function: () => {
        console.log("Command executed!");
      }
    }
  ],
  // Associate keybindings with commands
  keybindings: [
    {
      combo: { key: "k", ctrl: true },
      commandId: "myCommand"
    }
  ]
});

Command Configuration

Each command requires an id, label, and function:

{
  id: string,              // Unique identifier for the command
  label: string,           // Display name for the command
  function: () => void     // Function to execute when command is triggered
}

Keybinding Configuration

Each keybinding requires a combo and commandId:

{
  combo: {                 // Key combination
    key: string,           // The main key (single character or special key)
    ctrl?: boolean,        // Require Ctrl key (optional)
    shift?: boolean,       // Require Shift key (optional)
    alt?: boolean,         // Require Alt key (optional)
    meta?: boolean         // Require Meta/Command key (optional)
  },
  commandId: string        // ID of the command to trigger
}

Special Keys

For non-character keys, use one of these values:

Arrow keys: "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"
Function keys: "F1" through "F12"
Other special keys: "Escape", "Tab", "Enter", "Backspace", "Delete", "Home", "End", "PageUp", "PageDown"

Command Examples

app.registerExtension({
  name: "CommandExamples",
  commands: [
    {
      id: "runWorkflow",
      label: "Run Workflow",
      function: () => {
        app.queuePrompt();
      }
    },
    {
      id: "clearWorkflow",
      label: "Clear Workflow",
      function: () => {
        if (confirm("Clear the workflow?")) {
          app.graph.clear();
        }
      }
    },
    {
      id: "saveWorkflow",
      label: "Save Workflow",
      function: () => {
        app.graphToPrompt().then(workflow => {
          const blob = new Blob([JSON.stringify(workflow)], {type: "application/json"});
          const url = URL.createObjectURL(blob);
          const a = document.createElement("a");
          a.href = url;
          a.download = "workflow.json";
          a.click();
          URL.revokeObjectURL(url);
        });
      }
    }
  ]
});

Keybinding Examples

app.registerExtension({
  name: "KeybindingExamples",
  commands: [
    /* Commands defined above */
  ],
  keybindings: [
    // Ctrl+R to run workflow
    {
      combo: { key: "r", ctrl: true },
      commandId: "runWorkflow"
    },
    // Ctrl+Shift+C to clear workflow
    {
      combo: { key: "c", ctrl: true, shift: true },
      commandId: "clearWorkflow"
    },
    // Ctrl+S to save workflow
    {
      combo: { key: "s", ctrl: true },
      commandId: "saveWorkflow"
    },
    // F5 to run workflow (alternative)
    {
      combo: { key: "F5" },
      commandId: "runWorkflow"
    }
  ]
});

Notes and Limitations

Core Keybindings

Keybindings defined in the ComfyUI core cannot be overwritten by extensions. Check the core keybindings in these source files:

Additional Limitations

Some key combinations are reserved by the browser (like Ctrl+F for search) and cannot be overridden
If multiple extensions register the same keybinding, the behavior is undefined

Key Features

Custom commands: Register functions that can be triggered by keyboard shortcuts
Flexible key combinations: Support for modifier keys (Ctrl, Shift, Alt, Meta)
Special key support: Works with function keys, arrow keys, and other special keys
Extension integration: Commands are registered as part of extension definition
Multiple shortcuts: A single command can have multiple keybindings

Usage Notes

Commands must have unique IDs to avoid conflicts
Keybindings link to commands via the commandId field
Check for conflicts with existing core keybindings before registering
The meta key refers to the Command key on Mac and Windows key on PC
Commands can be triggered programmatically or through keybindings
Always test keybindings across different platforms and browsers

5.0 KiB Raw Blame History