Configure your PCB with VIA

VIA lets you remap any key on your Mechlovin' PCB in real time. Changes save straight to the board and travel with it between computers. This guide covers connecting your board, remapping keys, working with layers, and backing up your layout.

Platform · Chrome · EdgeDifficulty · BeginnerTime · ~10 minUpdated · 24 Sep 2026

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:

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.

  1. Download your PCB’s VIA JSON file from its page on this site, under the Downloads section.
  2. In VIA, open Settings (the gear icon, top-right) and turn on Show Design tab.
  3. Go to the new Design tab and load the .json file you downloaded.
  4. 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:

Remap a key

This is the core of VIA, and it’s just three clicks:

  1. Make sure you’re on Layer 0 (the base layer) using the layer buttons (top-left).
  2. Click the key on the on-screen keyboard that you want to change - it highlights.
  3. 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:

  1. Select the key you want to use as your “Fn” key (many builds use Caps Lock or a key near the spacebar).

  2. In the key set, open the Layers category.

  3. 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.
  4. 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.

  1. Open the Macros tab on the left-side menu and pick a slot (M0, M1, …).
  2. Type or record the sequence you want.
  3. Save it, then go back to Keymap, open the Macro category in the key set, and assign M0 to 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.

  1. Open the Save + Load tab.
  2. Click Save Current Layout and keep the .layout.json file 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

The board connects but the layout looks wrong

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.

A remapped key does nothing