How to use VIA to keymap & personalize your keyboard
VIA Configurator is a powerful application that allows users to personalize their own keyboards.
- Web-based: Windows, macOS, or Linux*? Does not matter, VIA is available to web-browsers**
- WYSIWYG – “what you see is what you get”: all keymap & settings are applied immediately, no flashing required!
Desktop App: VIA Releases (Github)
* For Linux users, additional OS-related settings are required
** Chrome and Edge only. Not available to Firefox and Safari 🙁
Please note, your keyboard must be loaded with “VIA-compatible Firmware” to use VIA. A keyboard may have many versions of firmware, some are not VIA-compatible. Contact your keyboard’s maker/manufacturer if you are not sure about this.
-> Please make sure you have the latest VIA-compatible firmware installed to your device.
This tutorial uses screenshots taken from VIA Web App, Chrome browser, Windows OS.
Step 0: Import VIA JSON file
For non-native VIA-compatible keyboards. If your keyboard is available in VIA Supported Keyboards, you can skip this step.
You only have to import this file once, per keyboard per browser.
1) Click the SETTINGS button and enable “Show Design tab”, the DESIGN button is now available.
2) Click “Load” button and select the JSON file.
Tips:
- If you already downloaded the file, try looking at your Downloads folder
- You can contact the maker/manufacturer of the keyboard to get JSON file.
- Regarding keyboards from KiwiKey, please refer to Download section.
What can go wrong?
After loading JSON file, there may be a red error message, try enabling “Use V2 definitions” and re-load file
- There are plenty JSON files out there, for different purposes. They share the same .json suffix, which is confusing, such as:
- Keyboard layout file, downloaded from Keyboard Layout Editor (KLE)
- QMK firmware definition file
- VIA keymapping backup file
- VIA-compatible file for keyboard (used in this guide)
Step 1: Connect the keyboard
! Your keyboard must be connected to the computer using USB cable !
In CONFIGURE page (first button), click the “Authorize device” button.
The browser will show a pop-up, just choose your keyboard and click Connect.
What can go wrong?
- As mentioned above, Firefox and Safari does not support communication to HID devices (means, our keyboards). Chrome and Edge are good to go.
- If you are a Linux user and having problem connect your keyboard to VIA, please read and follow this guide: Configuring udev rules for VIA and Vial on Linux.
Step 2: Keymap (remap keys)
The Configure page shows your keyboard layout & keymap.
At the upper-left corner, there are available layers (usually 4, the default/main layer is “0”), you can select each of them to edit.
At the bottom-left of the screen, there are various groups of keycodes:
- BASIC: letters, numbers, symbols, function keys and modifier keys
- MEDIA: keycodes for music/movie control (volume up/down, play – stop,…)
- MACRO: call a macro (there are 16 of them, all yours). Read more in Macro section.
- LAYERS: switching or toggling layers. Read more: QMK Layers.
- SPECIAL: some language-related changes, combination keys, some useful shortcuts. This also includes Mouse Keys* and Audio Keys**
- LIGHTING: controls the LEDs, including backlight and underglow lighting**
- CUSTOM (optional): dedicated keycodes, created by maker/manufacturer
** Audio Keys and Lighting is hardware-related, and must be enabled in the firmware,too.
What can go wrong?
Almost nothing, feel free to play around. You can roll back to default keymap, or load your backup file anytime.
Layer-keycodes are super useful, but can cause confusing sometimes.