Macros

The Layout Editor supports creating ZMK Macros, which let you trigger a sequence of actions with a single press.

Creating a Macro

To create a new macro, open the Macros panel in the Layout Editor and click New Macro. Give your macro a name (e.g. &my_macro), and optionally, add a description for your own reference.

Macro Actions

• Each macro consists of a sequence of actions, shown in the list in the center of the editor. Each action is either a ZMK behaviour action (for example &kp or &to) or a macro control action. You can reorder actions in the sequence at any time by dragging them. To remove an action, hover over it and then click the ⓧ icon.

You can add different types of action by clicking the buttons on the right of the list:

+ Action: Add a Behavior Action

Click this to to add an ZMK behavior action to the macro. Each action is displayed in a square "key" widget, and is configured in the same way as a key in the main layout editor. Click the & section in the top left to change the behavior type (such as &kp for keypress or &to for layer change), and the ∅︎ symbol(s) in the middle to change the configuration of that behavior.

⌄ Activation Mode: Change Macro Activation Mode

Select an action from this list to insert an Activation Mode change into your macro sequence.

The activation mode of your macro controls how key press actions in the macro sequence will be handled. When you insert an activation mode change into your macro sequence, the inserted mode will apply to all key press actions after it. The macro sequence always starts out in Tap mode.

There are three different activation modes:

• Tap (default): The key action will be pressed and immediately released.
• Press: The key action will be pressed and remain held down until either it's explicitly released or the macro ends.
• Release: The key action will be released if it's already being pressed.

⌄ Timing: Insert Macro Timing Action

Select an action from this list to insert a timing action into your macro sequence. There are three timing actions you can add:

• Wait (&macro_wait_time): Inserting a Wait will add a delay between actions in your macro sequence. Click the ∅︎ symbol to set the length of the wait in milliseconds.

• Pause for Release (&macro_pause_for_release): A macro starts running as soon as you press its trigger key. If you want some or all of its actions to be run only after the trigger key is released, you can insert a Pause for Release into your macro sequence. When the Pause for Release is reached, the macro will stop and wait for the trigger key to be released before continuing with the remaining actions in the sequence.

• Macro Tap Time (&macro_tap_time): This timing action doesn't have an effect of its own, but rather let you change the "Tap time" configuration in the middle of the macro. Click the ∅︎ symbol to configure the new tap time in milliseconds. The new tap time will apply to all "Tap" mode keypress actions following it in the macro sequence.

⌄ Parameters: Apply Macro Parameter

Macros can take parameters, which can be used as arguments for a behaviour in the macro sequence. This is useful if you want the same macro to behave differently depending on how you trigger it. You must first configure the parameters for your macro in the macro settings on the left hand side of the editor. Each parameter can be either a key code or or a layer. A macro can have up to two parameters.

To use the macro's parameters in a behavior action, first insert one of the Macro Parameter actions, and then the behavior action which you want it to be used on. There are four ways to use a parameter:

• 1 to 1: Use the first macro parameter as the first value of the behaviour action.
• 1 to 2: Use the first macro parameter as the second value of the behaviour action.
• 2 to 1: Use the second macro parameter as the first value of the behaviour action.
• 2 to 2: Use the second macro parameter as the second value of the behaviour action.

Macro Settings

• Default Tap Time (tap-ms): If the macro includes keypress actions, the duration (in milliseconds) that each key in the macro is held down for.

  • Default: 30 ms

• Default Wait Time (wait-ms): The delay (in milliseconds) between each behaviour in the macro.

  • Default: 15 ms

• Parameters (#binding-cells): Configures the number and type of parameters which the macro will take. Parameters can be either keycodes or layer references. Parameters are passed to behaviour actions by inserting macro parameter actions into the macro sequence.

Cloning a Macro

To create a new macro based on an existing macro, click the icon.

Deleting a Macro

To delete a existing macro, click the icon. Any references to the deleted macro in the layout will be converted to an empty &kp action.

Using Macros in your layout

To use a macro in your layout, first click the behavior type selector at the top left corner of a key, and select your macro by its name. If your macro takes parameters, click the ∅︎ icon(s) to configure the specific key codes or layers to be used for its parameters.