Skip to main content

Commands

Commands are actions that the user can perform from the Command Palette or by using a hot key.

Command

To register a new command for your plugin, call the addCommand() method inside the onload() method:

main.ts
import { Plugin } from "obsidian";
export default class ExamplePlugin extends Plugin {  async onload() {    this.addCommand({      id: "print-greeting-to-console",      name: "Print greeting to console",      callback: () => {        console.log("Hey, you!");      },    });  }}

Conditional commands#

If your command is only able to run under certain conditions, then consider using checkCallback instead.

When using the checkCallback, Obsidian first performs a check to see whether the command can run. To determine whether the callback should perform a check or an action, a checking argument is passed to the callback.

  • If checking is set to true, perform a check.
  • If checking is set to false, perform an action.
this.addCommand({  id: 'example-command',  name: 'Example command',  checkCallback: (checking: boolean) => {    if (checking) {      return isCommandPossible();    }
    doCommand();
    return true;  },});

Editor commands#

If your command needs access to the editor, you can also use the editorCallback, which provides the active editor and its view as arguments.

this.addCommand({  id: 'example-command',  name: 'Example command',  editorCallback: (editor: Editor, view: MarkdownView) => {    const sel = editor.getSelection()
    console.log(`You have selected: ${sel}`);  },}
note

Editor commands only appear in the Command Palette when there's an active editor available.

If the editor callback can only run given under certain conditions, consider using the editorCheckCallback instead. For more information, refer to conditional commands.

this.addCommand({  id: 'example-command',  name: 'Example command',  editorCheckCallback: (checking: boolean, editor: Editor, view: MarkdownView) => {    if (checking) {      return isCommandPossible();    }
    doCommand();
    return true;  },});

Hot keys#

The user can run commands using a keyboard shortcut, or hot key. While they can configure this themselves, you can also provide a default hot key.

warning

Avoid setting default hot keys for plugins that you intend for others to use. Hot keys are highly likely to conflict with those defined by other plugins or by the user themselves.

In this example, the user can run the command by pressing and holding Ctrl (or Cmd on Mac) and Shift together, and then pressing the letter a on their keyboard.

this.addCommand({  id: 'example-command',  name: 'Example command',  hotkeys: [{ modifiers: ["Mod", "Shift"], key: "a" }],  callback: () => {    console.log('Hey, you!');  },});
note

The Mod key is a special modifier key that becomes Ctrl on Windows and Linux, and Cmd on macOS.