Layers

Layers let you define multiple profiles of mappings and switch between them at runtime. Think of layers like the Fn key on a laptop keyboard — the same physical key produces different output depending on the active layer.

Defining layers

A layer is just a profile that is loaded into the layer stack when activated. So defining a profile and then activating it with a layer action is all you need to do to use a profile as a layer.

The layer stack

mapxr maintains a layer stack. At startup the stack contains only the default_layer. You can push additional layers on top or pop back to previous layers.

When resolving a trigger, mapxr searches from the top of the stack downward. The first matching mapping wins.

Stack (top to bottom):
  nav      ← searched first
  base     ← searched second (fallback)

Switching layers

Use layer actions in your mappings to navigate the stack:

A push layer action pushes the specified profile onto the stack above the current layer.

A pop layer action removes the top layer from the stack, returning to the previous layer.

An activate layer action clears the stack and pushes the specified profile onto it, making it the new top layer.

Layer Passthrough

Layer passthrough allows you to define a layer that passes through to the base layer when no matching mapping is found. So if you have layer 'A' above a layer 'B' with passthrough enabled, and no mapping is found for a trigger on 'A', mapxr will search layer 'B'.

To use layer passthrough, set the passthrough property to true in your profile settings tab

To prevent a trigger from being passed through to the base layer, you can set that trigger's action to block