What VIA is (and what you’ll need)
VIA is a free app for remapping your keyboard in real time. Because the layout lives on the board itself, it follows the keyboard to any computer. Plug into a different machine and your custom keymap is already there.
To follow this guide you’ll need:
- A Mechlovin PCB running VIA-enabled firmware: every QMK build on this site has VIA turned on, so if you flashed using the Flashing firmware with QMK Toolbox guide, you’re ready.
- A Chromium-based browser: Chrome, Edge, Brave, or Opera. VIA talks to the board through WebHID, which Firefox and Safari don’t support.
- A USB cable that supports data: the same cable you used to flash. Charge-only cables won’t work.
Note: VIA doesn’t apply to wireless (ZMK) boards. Those are customized in a different way. This guide is for wired QMK PCBs.
Open VIA
VIA runs entirely in your browser, there’s nothing to install.
Go to usevia.app and you’ll land on the Configure screen. If you prefer a standalone app, the desktop version is available from the VIA website, but the web app is the simplest place to start.
Connect your keyboard
Plug your keyboard into the computer, then in VIA click Authorize device (top of the screen). Your browser opens a small pop-up listing connected devices.
Select your keyboard from the list and click Connect. VIA reads the current layout off the board and draws it on screen.
Note: Close any other app that talks to the board first: QMK Toolbox, Vial, or a second VIA tab. Only one program can hold the connection at a time, and VIA may fail to connect if something else has it.
If your board appears and its layout loads, skip ahead to Find your way around. If VIA says the device is unrecognized, do the next step first.
Load your board’s definition
VIA ships with definitions for many keyboards built in, but a newer or less common Mechlovin’ PCB may not be recognized yet. When that happens, you load the board’s definition file by hand, a one-time step.
- Download your PCB’s VIA JSON file from its page on this site, under the Downloads section.
- In VIA, open Settings (the gear icon, top-right) and turn on Show Design tab.
- Go to the new Design tab and load the
.jsonfile you downloaded. - Return to Configure and click Authorize device again. Your board should now be recognized.
Note: You only need to do this once per board. After the definition is loaded, VIA remembers it.
Note: VIA has updated to Version 3, and previously loaded V2 definitions will not work. If this is the case for you, delete the current V2 definition in the Design tab and reload the latest V3 definition file.
Find your way around
With the board connected, the Configure tab on top shows a picture of your keyboard and a set of tabs down the side menu:
- Keymap: the main view, where you remap keys.
- Layouts: toggles for different layouts that your PCB supports. For example, Split Backspace, ANSI/ISO Enter.
- Macros: record a sequence of keystrokes onto a single key.
- Save + Load: export your layout to a file or load one back.
- Lighting: RGB controls, if your PCB supports them.
Remap a key
This is the core of VIA, and it’s just three clicks:
- Make sure you’re on Layer 0 (the base layer) using the layer buttons (top-left).
- Click the key on the on-screen keyboard that you want to change - it highlights.
- Pick the new key from the key set shown below the board.
The change is written to the board immediately. Press the key to confirm it now does the new thing.
Tip: Use the Key Tester tab to check your work. Every key you press lights up, so you can spot a mis-mapped or dead key at a glance.
If you can’t find a key in the default BASIC set, look through the other categories (MEDIA, SPECIAL, and so on).
Work with layers
A layer is an additional set of assignments that activates while you hold, or after you tap, a special key. That’s how a compact board fits arrows, function keys, and media controls without extra keys.
To set up a layer key:
-
Select the key you want to use as your “Fn” key (many builds use Caps Lock or a key near the spacebar).
-
In the key set, open the Layers category.
-
Choose a layer action. The two you’ll use most are:
- MO(1) - momentary: the layer is active only while you hold the key.
- TG(1) - toggle: tap to switch the layer on, tap again to switch it off.
-
Now click the Layer 1 button at the top left and remap keys. For example, put arrows on WASD and media keys on the number row.
Note: Keys you leave untouched on an upper layer fall through to the layer below, so you only need to fill in the keys you actually want to change.
Record a macro
A macro types a whole sequence from one key, handy for an email address, a Discord command, or a shortcut.
- Open the Macros tab on the left-side menu and pick a slot (M0, M1, …).
- Type or record the sequence you want.
- Save it, then go back to Keymap, open the Macro category in the key set, and assign
M0to any key.
Note: Keep macros short and avoid storing anything sensitive like passwords. A macro is plain text on the board and offers no security.
Adjust lighting
If your PCB has per-key or underglow RGB, the Lighting tab lets you change the effect, brightness, color, and speed. Move the sliders and the board updates live. These settings save to the board just like your keymap.
Note: No Lighting tab? Your PCB either has no addressable lighting or the current firmware build doesn’t expose it. That’s expected on many models.
Back up your keymap
Because your layout lives on the board, backing it up allows you to restore everything instantly after a firmware update or on a new board.
- Open the Save + Load tab.
- Click Save Current Layout and keep the
.layout.jsonfile somewhere safe.
To restore later, come back to this tab and use Load Saved Layout.
Note: Re-flashing firmware can reset the board’s memory to the layout’s defaults. Save a backup before you re-flash, then load it back afterwards.
Troubleshooting
VIA doesn’t list my keyboard when I click Authorize device
- Make sure you’re in Chrome or Edge. Firefox and Safari can’t connect.
- Try a different USB cable (charge-only cables won’t work) and a different port.
- Close QMK Toolbox, Vial, or any other VIA tab. Only one can hold the PCB.
- Confirm the PCB is running VIA-enabled firmware from this site.
The board connects but the layout looks wrong
- Load the correct VIA JSON for your exact model. See Load your board’s definition.
My changes don’t stick
Changes save automatically; there’s no Save button for remapping. If a key reverts, you may have edited it on the wrong layer. Check the layer buttons.
- If the board behaves erratically, reset its memory by holding the reset button while plugging in, then re-load your saved layout.
A remapped key does nothing
- Open Key Tester and press it. If nothing lights up, the switch may not be seated in its socket; if it lights up but types the wrong thing, remap it again on Layer 0.