Editing Layout

The MoErgo Layout Editor provides a workspace for you to create and modify your layouts.

You can always return to this workspace from anywhere in the editor by clicking Edit or Edit (Changes not saved) in the top menu bar.

Menu bar showing Edit

Menu bar showing Edit(Changes not saved)

Never Lose Your Work

While you are in the editing workspace, your progress is safe. You can freely browse other layouts to get inspiration or even copy parts of them, like layers or macros, without losing any of the changes you've made to your current layout.

For more details, see Copying Select Layers To Editing Layout.

Protecting Your Saved Layouts

In the MoErgo Layout Editor, any saved layout is protected from being changed directly. This is a key feature designed to safeguard your work and ensure that any layout you share or back up remains consistent forever.

If you want to make changes to a saved layout, you simply clone it. This creates a new, editable copy in your workspace while preserving the original version. This approach guarantees that any shared links to a layout will always point to the exact version you intended, without any risk of future edits breaking the link or causing confusion.

Understanding the Layout Editor

When you edit the layout, a screen like below will be shown.

Sections in the layout page

The editor is organized into the following sections, each handling a different aspect of your layout:

Title

Give your layout a descriptive and easy-to-remember name.

Tags

Tags are keywords that help you organize and find layouts. A good tag describes a key feature of the layout, such as the OS, application, or language it's designed for.

Tags must start with a lowercase letter and can only contain lowercase letters, numbers, and dashes.

Some good examples of tags include:

• OS: linux, mac, android
• Layout: azerty, colemak
• Language: japanese, german, swedish, norwegian, spanish
• Software or games: excel, vim, vscode, dota2

Locale

This changes the rendering of the legends on the keyboard to match the selected locale. This helps international users to design their keyboard layouts.

The default locale is en-US, which matches computers set to the United States English locale.

For more information please see International Keyboard Setup.

Layer selector

ZMK supports the concept of multiple layers. When you power on the keyboard, the base layer (layer #0) will be active. However, you can switch to different layers; thus, the same key can serve multiple purposes. This isn’t as confusing as it may sound, it’s similar to the Fn key on a laptop. There are two ways of switching layers: You can switch to another layer momentarily (while you hold down a trigger key, à la “Fn”) or indefinitely (until you switch layers again).

ZMK documentation for layers are at https://zmk.dev/docs/features/keymaps. Do note that an active higher-numbered layer has priority over the lower numbered layers.

On MoErgo Layout Editor, the layers are represented on the left side. The current layer shown on the layout is the layer highlighted.

When you hover over the circles, the full names of the layers appear and you can select a particular layer to show, or to perform action on a layer.

The available actions are:

• Reorder layer: Drag to move the layer to the desired layer priority
• Edit layer name: Change the layer name
• Duplicate layer: Create a new layer by duplicating the selected layer
• Delete layer: Delete the selected layer - do note that all reference to the layer will also be removed
• Add a new layer: Create a new layer from scratch

Notes

This optional section is for yourself and others to better understand the intention of the layout.

Macros

This section allows you to define macros.

A macro behavior defines a sequence of actions (e.g., pressing keys, holding modifiers) that are grouped together, which can be assigned to a key or a combo or other behaviors to automate complex tasks on your keyboard.

For more information please see Macros.

Hold-Taps

This section allows you to define hold-tap behaviors.

A hold-tap behavior allows a key to perform two different actions depending on how long you press it. If you tap the key briefly, it performs one action (e.g., typing a letter), and if you hold the key longer, it performs a different action (e.g., holding a modifier like Shift).

This allows you to maximize your keyboard’s functionality with the same key, depending on how you press it.

For more information please see Hold-Taps.

Combos

This section allows you to define combos.

Combos define rules which let you trigger a specific action when you press multiple keys at the same time. Instead of each key doing its usual function, the combo activates a new action only when the keys are pressed together within a short time interval.

For more information please see Combos.

Input Listeners

This section allows you to emulate mouse behaviors (such as mouse buttons, mouse movements and scroll).

For more information please see Mouse emulation.

Custom Defined Behavior

This optional section is for creating custom ZMK behaviors such as tap-dance by injecting your own code into the generated keymap DTSI file. This is advanced functionality; please use it with extreme caution.

For more information please see Advanced usage: Custom Defined Behaviors.

Custom Device-Tree

This optional section is for injecting your own code into the generated keymap DTSI file. This is advanced functionality; please use it with extreme caution.

For more information please see Advanced usage: Custom Device-Tree

Advanced Configuration

The Advanced Configuration section allows you to override the default ZMK firmware behaviors. For most users, it is not necessary to tune these advanced configuration settings.

Advanced Configuration

Some of the Advanced Configuration settings include:

• Enabling mouse support, for integrated pointing device or mouse emulation
• Enabling or disabling N-key rollover (NKRO)
• Enabling, disabling and configuring deep sleep
• Key debouncing characteristics to eliminate key chatter
• Debugging and troubleshooting settings

Note

Certain Advanced Configuration options, relating to HID descriptor such as NKRO, will not take effect until the HID descriptor is refreshed. Please see https://zmk.dev/docs/features/bluetooth#refreshing-the-hid-descriptor for details.

Key binding and key behaviors

Each key in each layer can be bound to a key behavior.

The upper left corner shows the behavior type. Please note that for &kp (key press) behavior, the behavior type is not shown.

The middle shows the keycode or the behavior parameter, depending on the type of behavior.

Bulk Edit Mode

Bulk Edit Mode allows you to quickly select and modify multiple keys on the active layer without opening the Key Editor.

To enable Bulk Edit Mode, hold down the Ctrl key (or ⌘ command on macOS) or click the icon in the top-right corner of the layout area.

Bulk Edit Mode is active only for the current layer and will automatically close if you switch layers.

Selecting Keys

When Bulk Edit Mode is enabled, the cursor changes to a crosshair. You can select keys in two ways:

• Lasso Selection: Click and drag to draw a selection area around multiple keys.
• Individual Selection: Click on individual keys to select or deselect them.

Target Key

The last key you select becomes the Target Key. It is highlighted with an orange border on the layout and displayed in the Bulk Edit toolbar.

The Target Key acts as the source for the Fill Keys operation and allows for quick recording. To assign a keycode to the Target Key, click on it in the toolbar and press the desired key or key combination on your physical keyboard.

Note

Some special keys or system shortcuts may not be recordable due to browser or Operating System limitations.

Mirror Keys

The Mirror Keys tool allows you to swap key bindings between the left and right sides of the keyboard. If a selected key has a symmetrical counterpart on the opposite hand, their values will be swapped.

In the example above, the key bindings are swapped, resulting in 7 and 6 on the left side and 5 and 4 on the right.

Swap Keys

When exactly two keys are selected, the Swap Keys tool becomes available. Clicking it swaps the bindings of the two selected keys.

Fill Keys

The Fill Keys tool allows you to assign the same binding to all selected keys at once. You can choose to fill them with:

• Target Key: Copies the binding from the Target Key.
• Empty: Clears the binding (&none).
• Transparent: Sets the binding to transparent (&trans).

Alternatively, you can press Delete or Backspace on your physical keyboard to clear the bindings of all selected keys.

Key Editor

Keys can be edited by clicking on them, which brings up the Key Editor. By default, Key Editor is opened on the first behavior parameter tab. To switch to another behavior, click on the navigation tab or press Ctrl+Left Arrow (or Cmd+Left Arrow on Mac).

Keyboard Navigation

The Key Editor supports keyboard navigation to speed up your workflow. To see the available hotkeys, hover over the orange keyboard hint icon.

The shortcuts are OS-specific, adapting to your operating system (e.g., using ⌘ command on macOS and Ctrl on Windows/Linux).

Behavior types

Next to the behavior name, its ZMK behavior type is displayed. MoErgo Layout Editor currently supports the following ZMK behavior types directly.

• &kp: key press
• &bootloader: enter bootloader mode
• &bt: bluetooth
• &cap_word: capitalize words
• &key_repeat: repeat key
• &kt: key toggle
• &lt: layer tap
• &mo: momentary layer
• &mt: mod tap
• &none: do nothing
• &output: output selection
• &reset: reset keyboard
• &rgb_ug: RGB underglow control
• &sk: sticky key
• &sl: sticky layer
• &to: to layer
• &trans: transparent
• &mmv: mouse X/Y movement
• &mkp: press/release mouse buttons
• &msc: vertical and horizontal mouse scroll

For more information on the ZMK key behaviors, please see ZMK documentation at https://zmk.dev/docs

In additional to the above standard ZMK behaviors, MoErgo Layout Editor also supports the following pseudo behaviors:

• &bt_0: select bluetooth profile 0 with a single quick-tap, explicitly disconnect bluetooth profile 0 with a double quick-tap
• &bt_1: select bluetooth profile 1 with a single quick-tap, explicitly disconnect bluetooth profile 1 with a double quick-tap
• &bt_2: select bluetooth profile 2 with a single quick-tap, explicitly disconnect bluetooth profile 2 with a double quick-tap
• &bt_3: select bluetooth profile 3 with a single quick-tap, explicitly disconnect bluetooth profile 3 with a double quick-tap
• &magic: quick-tap to show RGB indicators. Press to momentarily switch to magic layer
• &lower: hold to momentarily switch to lower layer. Double tap to persistently switch to lower layer.
• &layer: hold to momentarily switch to the target layer. Double tap to persistently switch to the target layer. This is a generalization of &lower
• Custom: A special pseudo behavior to allow arbitrary key mapping, to be used with Custom Defined Behavior. For more information please see Custom Defined Behaviors.

&magic pseudo behavior

This is a special MoErgo-defined pseudo behavior defined as a macro. For a key bound to this behavior,

• A quick tap will activate the LED indicators.

User guide for LED indicators

Glove80

Glove80 User Guide "Indicators"

• While holding the key, the keyboard will momentarily switch to the layer with the label Magic (note: case sensitive). After key release, the keyboard will automatically revert back to the current layer.

Mapping of Magic key on factory default layout

Glove80

On a standard Glove80 layout, LH C6R6 key is mapped to the &magic behavior in all layers.

&lower pseudo behavior

This is a special MoErgo-defined pseudo behavior defined as a macro. For a key bound to this behavior,

• While holding the key, the keyboard will momentarily switch to the layer with the label Lower (note: case sensitive). After key release, the keyboard will automatically revert back to the current layer
• If double tapped, the keyboard will permanently switch to layer with the label Lower.

Mapping of Layer key on factory default layout

Glove80

On a standard Glove80 layout, LH T3 key is mapped to the &lower behavior in the Base Layer (layer #0).

&layer pseudo behavior

This is a special MoErgo-defined pseudo behavior defined as a macro. It has a target layer as its parameter.

For a key bound to this behavior,

• While holding the key, the keyboard will momentarily switch to the target layer. After key release, the keyboard will automatically revert back to the current layer
• If double tapped, the keyboard will permanently switch to the target layer.

NOTE: This pseudo behavior cannot be used in a macro definition.

Bluetooth &bt_0 &bt_1 &bt_2 &bt_3 pseudo behaviors

These 4 pseudo behaviors provide the following functionality:

• On a single quick-tap, switch the keyboard to the respective designated bluetooth device, if the bluetooth device is currently connected
• On a double-tap, explicitly disconnect the respective designated bluetooth device, if the bluetooth device is currently connected and is not the current active BLE profile. This functionality is useful for tablets and phones that disable on-screen keyboard, even if the device is not the current selected output device.

Underneath the bonnet, these behaviors are each implemented as a tap-dance and a macro, The macro sets output to bluetooth, and then sets the bluetooth device to the designated bluetooth device.

As an example &bt_0 is defined as:

    behaviors {
        bt_0: bt_0 {
            compatible = "zmk,behavior-tap-dance";
            label = "BT_0";
            #binding-cells = <0>;
            tapping-term-ms = <200>;
            bindings = <&bt_select_0>, <&bt BT_DISC 0>;
        };
    }


    macros {
        bt_select_0: bt_profile_macro_0 {
            label = "BT_0";
            compatible = "zmk,behavior-macro";
            #binding-cells = <0>;
            bindings
                = <&out OUT_BLE>,
                  <&bt BT_SEL 0>;
        };
    };

Bluetooth clear all profiles &bt BT_CLR_ALL

The &bt behavior has been extended with an additional parameter BT_CLR_ALL

When bound to &bt BT_CLR_ALL, the key will initiate clearing all Bluetooth bindings (excluding the binding to the right hand).

Selecting keycode

The Keycode Selector allows you to browse and assign keycodes to your layout. It consists of a searchable Keycode List on the left and a Keycode Details configurator on the right.

Keycode Selector Interface

Keycode List

The Keycode List displays commonly used keycodes for easy selection.

To find a specific keycode, use the Quick Filter input. This searches through all available keycodes, even those not currently visible in the list. The counter to the right of the input shows the total number of matching keycodes found in the database.

Categories

Use the Categories menu, located to the left of the filter input, to filter which keycodes appear in the list.

To customize these categories, click the Gear icon within the menu.

The settings menu allows you to toggle the visibility of specific categories. You can also enable Advanced Keycodes to reveal specialized or less common keycodes for each category.

Shifted Keycodes

Many keycodes produce a different character when a modifier like Shift or AltGr is held. For example, the 3 key typically produces # when Shift is held.

It is important to understand that a keyboard only sends key presses to the computer, not actual letters or symbols. The computer’s operating systems language setting (like “en-US”) decides what those key presses mean.

Because of this dependency on your OS and Locale settings, the Layout Editor provides visual hints about the expected output based on your selected configuration.

Keycode Recorder

To quickly assign a keycode, click inside the specific keycode input field. An orange underscore will flash, indicating the Keycode Recorder is active.

Simply press the desired key or key combination on your physical keyboard, and the corresponding keycode will be automatically selected.

Note

Some special keys or system shortcuts may not be recordable due to browser or Operating System limitations.

Saving a Layout and building firmware

To save or build a layout, use the multi-button. The Save action is on the left, and the Save and Build action is on the right.

During the layout saving process, the MoErgo Layout Editor will perform a comprehensive correctness check on the layout being edited.

If there are any errors, a screen like the one below will be displayed.

Layout saving error

You must fix all issues before the layout can be saved.

Once the firmware is successfully built, the MoErgo Layout Editor will exit layout editing mode and redirect you to the layout viewing URL of the layout that was just built.