Skip to main content

Layer Behaviors

Summary​

Often, you may want a certain key position to alter which layers are enabled, change the default layer, etc. Below are the list of behaviors that can be used to activate and deactivate layers.

note

Multiple layers can be active at the same time and activating a layer will not deactivate layers higher up in the "layer stack".

Layer numbers start at 0 following the order they are defined in the keymap node, for example &mo 3 would activate the 4th layer node defined in the keymap. See Layers for more information.

Momentary Layer​

The "momentary layer" behavior enables a layer while a certain key is pressed. Immediately upon activation of the key, the layer is enabled, and immediately upon release of the key, the layer is disabled again.

Behavior Binding​

  • Reference: &mo
  • Parameter: The layer number to enable while held, e.g. 1

Example:

&mo 3

Layer-Tap​

The "layer-tap" behavior enables a layer when a key is held, and outputs a keypress when the key is only tapped for a short time.

Behavior Binding​

  • Reference: &lt
  • Parameter: The layer number to enable while held, e.g. 1
  • Parameter: The keycode to send when tapped, e.g. A

Example:

&lt 3 SPACE

Configuration​

You can configure a different tapping term or tweak other properties noted in the hold-tap documentation page in your keymap:

&lt {
    tapping-term-ms = <200>;
};

/ {
    keymap {
        ...
    };
};
info

Functionally, the layer-tap is a hold-tap of the "tap-preferred" flavor and a tapping-term-ms of 200 that takes in a momentary layer and a keypress as its "hold" and "tap" parameters, respectively.

For users who want to send a different keycode depending on if the same key is held or tapped, see Mod-Tap.

Similarly, for users looking to create a keybind like the layer-tap that depending on how long the key is held, invokes behaviors like sticky keys or key toggles, see Hold-Tap.

To Layer​

The "to layer" behavior enables a layer and disables all other layers except the default layer.

Behavior Binding​

  • Reference: &to
  • Parameter: The layer number to enable, e.g. 1

Example:

&to 3

Toggle Layer​

The "toggle layer" behavior enables a layer if it is currently disabled, or disables it if enabled.

Behavior Binding​

  • Reference: &tog
  • Parameter: The layer number to enable/disable, e.g. 1

Example:

&tog 3

Configuration​

Toggle mode​

If you wish to ensure that a layer is toggled on or off specifically, rather than switching between the two states, then you can do so with the toggle-mode property. Define a new behavior and assign "on" or "off" to toggle-mode:

/ {
    behaviors {
        tog_on: toggle_layer_on_only {
            compatible = "zmk,behavior-toggle-layer";
            #binding-cells = <1>;
            display-name = "Toggle Layer On";
            toggle-mode = "on";
        };
    };
};

You can then use &tog_on in place of &tog whenever you wish to only toggle a layer on, and not toggle it off. An "off" version of the behavior can be defined similarly.

Conditional Layers​

The "conditional layers" feature enables a particular layer when all layers in a specified set are active. For more information, see conditional layers.

Defines to Refer to Layers​

When working with layers, you may have several different key positions with bindings that enable/disable those layers. To make it easier to refer to those layers in your key bindings, and to change which layers are where later, you can add a set of #defines at the top of your keymap file, and use those defines in your keymap.

For example, if you have three layers, you can add the following to the top of your keymap:

#define DEFAULT 0
#define LOWER   1
#define RAISE   2

This allows you to use those defines, e.g. LOWER later in your keymap.

&mo LOWER  // equivalent to &mo 1