obsidian/modals/modal-command-builder

A builder for a modal’s control strip.

ModalCommandBuilder assembles the strip of controls shown at the bottom of a modal: keyboard-command hints (ModalCommandBuilder.addKeyboardCommand), interactive checkboxes bound to a modifier+key shortcut (ModalCommandBuilder.addCheckbox), and dropdowns bound to a modifier+key shortcut (ModalCommandBuilder.addDropDown). Chain the add* calls, then apply everything to a modal with ModalCommandBuilder.build:

new ModalCommandBuilder()
  .addKeyboardCommand({ key: 'Enter', modifiers: ['Mod'], onKey, purpose: 'to create' })
  .addCheckbox({ key: '1', modifiers: ['Alt'], onChange, onInit, purpose: 'Fix footnotes' })
  .build(modal);

The strip is described by two independent axes:

• Where it is hosted. A SuggestModal in ModalCommandsRenderMode.Instructions mode keeps Obsidian’s own instruction bar (setInstructions + instructionsEl). Every other target — a plain Modal, or a bare ModalCommandsHost of an element plus a Scope — gets a strip element the builder creates itself. - How each control looks. ModalCommandsRenderMode.Instructions renders the purpose text with an inline checkbox or dropdown; ModalCommandsRenderMode.Buttons renders one clickable button per control, carrying its pressed and disabled state.

The axes are independent because a button strip inside a SuggestModal is a real combination.

ModalCommandBuilder.build always registers the essential navigation/action key handlers, but only renders the control UI and registers the option-toggle shortcuts when ModalCommandBuilderBuildOptions.shouldShowInstructions is true (the default).

Classes

Class	Description
ModalCommandBuilder	Builds a modal’s control strip from keyboard commands, interactive checkboxes, and dropdowns, then applies them to a modal via ModalCommandBuilder.build.

Interfaces

Interface	Description
CheckboxCommand	A checkbox command shown in a modal’s control strip and bound to a modifier+key shortcut that toggles it.
CommandBase	The members every command shares.
DropDownCommand	A dropdown command shown in a modal’s control strip and bound to a modifier+key shortcut that cycles through its options. Supported in ModalCommandsRenderMode.Instructions mode only.
KeyboardCommand	A keyboard command shown in a modal’s control strip and optionally bound to a modifier+key handler.
ModalCommandBuilderBuildOptions	Options for ModalCommandBuilder.build.
ModalCommands	The handle returned by ModalCommandBuilder.build.
ModalCommandsHost	A bare host for a control strip: the element to render into, plus the scope to register shortcuts with.

Types

Type	Description
ModalCommandsTarget	Every target ModalCommandBuilder.build accepts.

Enums

Enum	Description
ModalCommandsRenderMode	The way ModalCommandBuilder.build renders each control.