ZMK Key Remapping Guide

This guide applies to ZMK keyboards of every layout: compact single-piece boards, standard keyboards, and split keyboards. The key difference is not the number of halves, but whether the firmware supports ZMK Studio for live editing or requires a Keymap Editor workflow followed by a firmware flash.

Choose your remapping method

ZMK Studio is the quickest route when your keyboard firmware supports it. Connect the keyboard by USB, edit the layout in a browser, save, and the change takes effect without reflashing.

Keymap Editor is for keyboards whose maker provides a ZMK configuration repository. You fork that repository to your GitHub account, make visual changes, let GitHub Actions build a new firmware, then flash the resulting file to the keyboard.

If you are unsure which route to use, check the product documentation first. Do not flash a firmware intended for another keyboard model.

Before changing any key

1. Start with one small change and test it before making more.
2. Remember that the layout view represents physical switch positions, not the legend printed on each keycap.
3. Note which layer you are editing. The base layer is often called Default, Base, or layer 0; higher layers hold numbers, symbols, navigation, media, or Bluetooth controls.
4. Keep a known working firmware file or configuration commit so you can return to it if needed.

These rules are the same for a single keyboard and a split keyboard.

Method 1: remap with ZMK Studio

Use ZMK Studio only when the keyboard firmware explicitly supports it. Connect the keyboard to the computer with a data-capable USB cable, then open https://zmk.studio in Google Chrome or Microsoft Edge.

1. Choose USB and select your keyboard in the browser device picker.
2. Select the layer you want to edit.
3. Click the physical key position in the layout.
4. Choose the new action from the key library, such as a letter, media key, mouse key, or layer action.
5. Save the change, then test the key before disconnecting.

For a split keyboard, connect the half identified by the maker as the central, primary, or USB half. You still edit one complete keymap; the other half normally does not need a separate change. For a single keyboard, simply connect its USB port.

Method 2: remap with Keymap Editor

Use this route when your keyboard maker supplies a ZMK configuration repository. First create your own copy of that repository on GitHub with Fork. This keeps your changes private to your account and lets GitHub build your own firmware. If GitHub asks you to enable Actions for the new repository, enable them.

Open https://nickcoutsos.github.io/keymap-editor/, sign in with GitHub, and select your forked repository. After the layout loads:

1. Select the target layer.
2. Click the physical key position to change.
3. Search for or select the desired keycode or action.
4. Use the layer selector to edit function, navigation, Bluetooth, or media layers.
5. Select Save, then Commit to send the change to GitHub.

A commit starts the repository's GitHub Actions workflow. Wait for the build to complete successfully, then download the firmware artifact from the workflow page and unzip it.

Add and use layers

Layers let a small keyboard do more without adding physical keys. A typical arrangement has a base layer plus a function or navigation layer. Keep commonly used keys transparent or unchanged on higher layers, and place the new actions only where they help.

A layer key may activate a layer only while held, toggle it on and off, or switch to it. Before replacing a key with a layer action, make sure you still have a reliable way back to the base layer. Test layer keys immediately after flashing or saving.

Flash firmware safely

Only the Keymap Editor route needs this step. Download the successful GitHub Actions artifact, unzip it, and use the firmware file intended for your exact keyboard or controller. Put the keyboard into bootloader mode using the method from its product guide, such as a reset button, a double reset, or a documented key combination. A bootloader drive commonly appears as a removable USB drive; copy the matching .uf2 file to it and wait for the keyboard to restart.

A single keyboard usually has one firmware file. A split keyboard may have a file for each half, a central-half file for ordinary keymap changes, or a special reset firmware. Follow the filenames and flashing order supplied with your model rather than assuming every split keyboard uses the same process.

Troubleshooting

ZMK Studio cannot find the keyboard: use a data USB cable, connect the documented USB or central half, and confirm that the installed firmware supports ZMK Studio.

Keymap Editor does not show your board: confirm that you selected your own fork and that the repository contains the maker-provided workflow and keymap files.

The firmware build fails: open the failed GitHub Actions run, correct or revert the latest change, then commit again.

A Bluetooth key no longer works: clear the old pairing on the computer or phone only when the product guide recommends it, then follow the keyboard's documented pairing sequence.

The layout is wrong after flashing: return to bootloader mode and flash the last known-good firmware.