Keyboard enthusiasts have always preferred their own bespoke layout, leading to the development of remapping software and custom keyboards. However, there were some limitations with how you can configure these keyboards and save those settings. QMK and VIA are a great solution for this, offering the ability to remap keys, create macros, and adjust settings for different operating systems with ease, even featuring onboard memory in some cases. This article will guide you through configuring a QMK-supported keyboard using VIA, ensuring you can tailor your typing experience without diving too deep into coding.

Image of a green CIY GAS67 cutom built keyboard with
How analog optical switches differ from mechanical switches

Out with the old, in with the optical

By 

What are QMK and VIA?

QMK (Quantum Mechanical Keyboard) Firmware is an open-source software that allows you to customize every aspect of your keyboard, from key bindings to macros. However, QMK requires you to flash your keyboard's controller with new firmware every time you make a change, which can be daunting for some and extremely impractical.

Enter VIA, a user-friendly interface that works as a configurator for the QMK firmware, allowing you to make real-time changes to your keyboard without the need to flash firmware constantly. This combination offers a greater level of customization, from backlight effects and macros to custom keycodes and mouse commands across different keymap layers.

Preparing your keyboard

First things first, you need to ensure your keyboard is compatible with QMK and VIA. VIA supports around 1400 keyboards now. Check the VIA website to see if your model is listed. If it's not, you are probably out of luck, but there is always a probability that you might find the correct JSON file in communities and forums. In this guide, I have used a MonsGeek M1 Wired board. I downloaded the JSON file for this keyboard directly from the manufacturer’s website.

There are two types of JSON files available for download. They are V2 and V3 files. V2 JSON files are simpler to code and modify, but depending on the keyboard, it might miss some features like controls for the rotary encoders and OLED panels. On the other hand, V3 JSON files are more advanced and support these newer features, but they are a bit more complex to code and modify. The availability, variant (V2 or V3), and features of the JSON files depend on the source of the file, which is almost always the manufacturer. Note the version you have downloaded (defined by the source or evident from the file name) before moving on to the next steps.

Ensure that the JSON file you are downloading is free from viruses or other malicious software.

How to access VIA

Now, let's get VIA up and running on your computer. VIA is available for Windows, macOS, and Linux, and even as a web app, making it accessible to most users. In this guide, I have used the website, but you can choose to go with the apps for your respective platforms. The steps remain the same, irrespective of the method you choose to access VIA.

  1. Visit the VIA website. Alternatively, if you want to download the software, you can access VIA’s official GitHub releases page and download and install the proper file, depending on your operating system.
    Image showing the primary screen of the VIA configurator with the "Authorize Device" button highlited
  2. In most cases, if your keyboard is supported by VIA, it will automatically show up on the main screen, but just in case it does not, try clicking on the Authorize Device button.
    Image showing the popup after clicking on the authorize device button showing the list of available HID devices, higlighted in red.
  3. If your keyboard is not being automatically detected by VIA, try uploading the proper JSON file. Navigate to the Settings tab and click on the Show Design tab option.
    screenshot showing the show design tab option highlighted in settings
  4. You should find a new tab marked with a paintbrush icon. Click on that icon.
    screenshot showing load option in design tab
  5. Depending on the JSON file you have downloaded (V2 or V3, which should be indicated in the file name), you can check the option marked Use V2 definitions (deprecated) or leave it unchecked. Then proceed to upload the JSON file for your particular keyboard by either clicking on the Load button or dragging the file into the upload box.
    Image showing the final design tab of VIA after uploading the JSON file.
  6. You should now be able to customize your keyboard from the main screen of VIA.

Configuring keybindings using VIA

Now that the setup is complete, you can finally use VIA to change anything about your keyboard, whether keybindings, macros, or lighting.

  1. Navigate to the main screen where your keyboard layout is displayed.
    Screen shot showing the landing page of keybinding tab in VIA
  2. Click on the key you want to reprogram. For example, I chose "Home".
    Screen shot showing the Home button higlighted
  3. Now click on the option you want to assign to that key. I chose "Num Lock"
    Screen shot showing the home button reprogrammed to be the num lock button using VIA
  4. When it comes to binding lighting control to keys, you can do that by switching over the Lighting section under keybinding and then following the keybinding process as usual.
    Image showing lighting key bindings
  5. You can also browse for more options for a specialized selection of keys for media control, layers, and special buttons.
    Image showing Media based keybindings

How to set up and bind Macros using VIA

One of the primary uses of VIA is to design and map Macros. To do so, you have two options. You can record the key strikes to set the macro or code it yourself. If you choose the latter route, you can refer to the QMK website to find out about the key codes. For this guide, I chose to record my keystrokes.

  1. Navigate to the Macro tab which is available under the keybinding section.
    Screenshot showing the landing page for Macro with the Macro icon highlighted in red
  2. Click on the Fullscreen button.
    Screenshot showing the Fullscreen option highlighted in red
  3. Click on the record button and press the shortcut to code into the macro. In this guide, I replicated the Print screen button as the MonsGeek M1 does not have a print screen button by default.
    Screenshot showing the Record function highlihted in red
  4. To do so, I logged the keystroke Win+Shift+S.
    Screenshot showing recorded macro
  5. Remember the slot under which you are logging a particular keystroke. I assigned the keystroke to M0. There are in total sixteen slots for custom macros.
    Screenshot showing asignee slot for the macro
  6. Head back to the key binding tab and click on Macros.
    Screen shot showing the Macro option under keybinding section marked in red
  7. Now click on the button that you want to assign to this macro. I chose the Home button. That way, when I press the home button, Windows sees it as pressing Win+Shift+S which is the shortcut for Snip and Sketch (or Snipping tool if you are on Windows 11).
    Image showing Media based keybindings

How to manage layers in VIA

Configuring layers in VIA is a clever way to multiply the functionality of your keyboard without adding extra keys. Layers allow a single key to perform multiple functions, depending on the active layer. It's especially useful for compact keyboards that might lack physical space for all desired keys.

  1. You can switch between each layer by clicking on layer numbers in the upper left corner of the main screen and assign keys based on each layer.

Customize lighting using VIA

Image showing lighting controls in VIA

You can customize the lighting pattern, brightness, and speed from the lighting section.

Saving and loading of customized JSON filesImage showing the export and import option for JSON files in VIA

Once you are done with all the customizations, you can also export the settings as a customized JSON file to transfer or backup them. This feature can come in handy if you are working on many mechanical keyboards and prefer having custom settings for all of them. To export the settings, click on the floppy disk-like save button and click on Save. To import a previously saved JSON file, click on the Load button.

Test your configuration

Image showing the keybaord tester section within VIA

The VIA keyboard tester is an integrated tool that allows users to test each key press in real-time, ensuring all custom configurations are correctly applied and functional. After configuring your keyboard, it's important to test all changes. Type, switch layers, activate macros, and ensure everything works as intended. If something isn't right, VIA makes it easy to adjust settings on the fly.

Final thoughts

With QMK and VIA, customizing your keyboard goes from a daunting task to an intuitive, straightforward process. Whether it's remapping keys, setting up macros, managing layers, or adjusting lighting, VIA equips you with the tools to tailor your keyboard exactly to your needs, without the hassle of constant firmware flashes. The flexibility and real-time customization that VIA offers, combined with QMK's powerful backend, make for a robust setup that caters to both newcomers and seasoned enthusiasts alike. As more people pick up interest in customized keyboards, tools like VIA and QMK stand out for their ability to make personalization accessible and enjoyable for everyone. Remember, the key to a fully optimized typing experience lies in exploring, experimenting, and fine-tuning your setup until it's just right.