Remapping a Keyboard with VIA
How to change what your keys do, build a layer and record a macro, with no firmware flashing and nothing to compile.
Most custom keyboards run QMK, an open firmware that lets every key be reassigned. Historically that meant editing C, compiling firmware and flashing the board, and getting it wrong meant a keyboard that did nothing.
VIA removed all of that. It is a desktop application that talks to the running firmware, so changes apply the moment you make them, with nothing to compile and no way to brick the board.
This is the single most underused feature of a custom keyboard, and it is the entire argument for buying a small one.
Before you start: is your board supported
VIA only works with boards whose firmware was built with VIA support. That is most custom kits and almost no mainstream keyboards.
Check first at caniusevia.com, which lists supported boards. If yours is not there, three possibilities: the manufacturer publishes a definition file you load manually, the board uses its own software instead (Keychron and Glorious both do), or it runs QMK without VIA and needs the older compile-and-flash route.
Do not buy a board assuming it does this. Check the listing.
Getting it
VIA now runs in the browser at usevia.app, which is the easiest route and needs no install. It uses WebHID, so it works in Chrome and Edge and not in Safari or Firefox.
There is also a downloadable application, which is the one to use if you would rather not grant a web page access to a USB device. Either way the board must be plugged in by cable: VIA cannot configure a keyboard over Bluetooth.
Step 1: let it find the board
Plug in, open VIA, and it should detect the keyboard and draw your actual layout on screen.
If it does not: check the cable is a data cable rather than charge-only, check the board is in the supported list, and on the web version accept the device permission prompt. A board with a physical Mac/Windows or wired/wireless switch sometimes needs to be in a particular position.
Step 2: remap a key
The screen shows your layout on top and a keyboard of available assignments below.
- Click the key you want to change. It highlights.
- Click what you want it to become.
That is it. The change is live immediately, and it is stored on the keyboard rather than on the computer, which is the part people do not expect: the board keeps its layout when you plug it into a different machine. No software needs to be installed on the other computer.
Somewhere in the assignment panel is Any, which lets you type a keycode directly. That is where the obscure things live.
Step 3: layers, which are the actual point
A layer is a complete second set of assignments for every key, reached by holding a modifier. This is how a 60 percent keyboard has arrow keys and a function row without having the keys.
VIA shows a layer selector, usually numbered 0 to 3. Layer 0 is what the board does normally. Layers 1 and up are what it does while a layer key is held.
To build one:
- On layer 0, assign a key to be your layer key. In the assignment panel look for Layers, then
MO(1), which means “momentarily activate layer 1 while held”. Caps Lock and the right-hand modifiers are the usual choices. - Switch to layer 1.
- Assign the keys you want. Anything left as transparent, shown as
▽, falls through to layer 0.
The arrangement most people arrive at, and worth copying before inventing your own: arrows on IJKL or HJKL under the right hand, Delete somewhere near Backspace, and the function row on the number row.
Two other layer keycodes are worth knowing. TG(1) toggles a layer on and off rather than holding it, and LT(1, KC_SPC) makes one key do two jobs, a layer when held and a normal key when tapped.
Step 4: macros, if you need them
The Macros tab records a sequence of keystrokes and assigns it to one key.
Genuinely useful for a repeated string, an email address, a shell command. Less useful than it sounds for anything requiring timing, because macros replay fast and some applications drop input. If a macro misbehaves, add a delay between the steps.
One thing not to do: do not put a password in a macro. It is stored in plain text on the keyboard, it types itself into whatever has focus, and anyone who plugs the board into their own machine can read it back out with the same tool you used to write it.
Step 5: lighting
If your board has LEDs, the Lighting tab handles brightness, effects and speed, and on per-key boards the individual colours.
Worth knowing that lighting effects are the most common cause of a board behaving oddly after a firmware update, so if something is wrong immediately after one, turn the effects off before investigating anything else.
If you break it
You cannot brick a board with VIA, which is its main advantage over flashing. Every change is a setting, not firmware.
If the layout is badly wrong, there is a reset in the Design or Settings area that clears it back to the manufacturer’s default. The worst case is redoing your layers.
The one way to actually lose access is to remap every key that could reach your layer key, leaving no way to get to the layer holding the fix. If that happens, plug into another machine, open VIA, and reset: VIA does not need the keyboard to be usable in order to reconfigure it.
What to do first
Assign a layer key and put arrows on it, then use the board for a week without touching anything else.
Arrows under your right hand without moving your hand is the change that converts people, and it is the reason a 60 percent board is viable at all. Once that is muscle memory, the rest of the layer will suggest itself from whatever you keep reaching for and failing to find.