Layer Switching

The layer switching feature in OverKeys allows you to switch between multiple custom keyboard layers, each with its own key arrangement and activation method. This is particularly useful when using keyboard firmware like QMK or ZMK, where you can configure the keyboard to have different layers.

While OverKeys doesn't directly communicate with QMK or ZMK (unlike its Kanata integration), you can still visualize different layers by configuring your keyboard firmware to send designated trigger keys (typically F13-F24) when switching layers.

For a more native layer switching experience and synchronization, consider using the Kanata integration instead.

Setup Instructions

Turning the setting on

1. Open OverKeys
2. Right-click the OverKeys icon in the system tray
3. Select Preferences
4. Go to the General tab
5. Toggle the Enable advanced settings option
6. Toggle the Use user layouts option

Using Configuration File

1. Right-click the OverKeys tray icon

2. Select Preferences

3. Go to the General tab

4. Click Open Config

5. In the JSON file, edit the userLayouts array and set the defaultUserLayout field. Each layer must include:

   • name: Unique name for the layer
   • keys: The layout rows for this layer
   • trigger: The key used to activate this layer (usually F13–F24, or any key from Supported Keys)
   • type: Either "held" (layer is active while key is held) or "toggle" (press once to activate, again to deactivate)

   {
       "userLayouts": [
           {
               "name": "Extend",
               "keys": [
                   ["`", "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "-", "=", "BSPC"],
                   ["UNDO", "CUT", "COPY", "PASTE", "FIND", "DEV", "⇤", "↑", "⇥", "", "", ""],
                   ["1", "2", "3", "4", "5", "⤒", "←", "↓", "→", "⤓", ""],
                   ["6", "7", "8", "9", "0", "", "", "", "", ""],
                   [" "]
               ],
               "trigger": "F14",
               "type": "held"
           },
           {
               "name": "Symbol",
               "keys": [
                   ["`", "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "-", "=", "BSPC"],
                   ["'", "<", ">", ":", "@", "~", "\"", "{", "}", "%", "[", "]"],
                   ["!", "-", "+", "=", "`", "|", ".", "(", ")", "?", "'"],
                   ["^", "/", "*", "_", "\\", "&", "$", "[", "]", "#"],
                   [" "]
               ],
               "trigger": "F15",
               "type": "toggle"
           }
       ],
       "defaultUserLayout": "QWERTY"
   }
   

   Note: For best compatibility, use F13–F24 as triggers, or any key (not alias) listed in Supported Keys. The type field determines if the layer is active only while the trigger is held ("held") or toggles on/off with each press ("toggle").

6. Save the file

7. Right-click the tray icon and click Reload config to apply changes

Creating Custom Layers

You can add as many layers as you want to the userLayouts array. Each must have a unique name, a keys array, a trigger, and a type. Refer to Custom Layouts documentation when defining your layers.

Format Guidelines

1. Trigger: The key that activates the layer. F13–F24 are recommended, but any supported key can be used.
2. Type: "held" for momentary layers, "toggle" for persistent layers.

Implementation Notes

• User layers are loaded when OverKeys starts or when you toggle the setting.
• If a layer's trigger key is pressed, the corresponding layer will be activated according to its type.
• Best case scenario is if the key can be configured so that it could both send a layer change and the trigger key in one press, i.e., combo or macro.
• Layer change listening and Kanata integration cannot be used simultaneously.
• When using Kanata integration, the trigger and type fields in the layer configuration are ignored, as layer switching is controlled by Kanata.

Troubleshooting

• Ensure each layer in userLayouts has a unique name.
• The defaultUserLayout must match one of the defined layer names or natively supported layouts.
• If layers do not appear or do not switch, verify that Use user layouts is enabled and your configuration is valid.
• Make sure your trigger key is not used by another application or system shortcut.