feat: add key modifiers to layout configuration

README.md

@@ -152,6 +152,7 @@ This project was initially developed to help with the creator's system-wide prac
 - **Auto-hide**: The keyboard hides automatically when not in use
 - **Keymap styles**: Supports staggered, matrix, and split matrix (5-col and [6-col](/docs/advanced/6-column-layouts.md)) styles
 - **User configurations**: Add and use [custom keyboard layouts](/docs/advanced/custom-layouts.md) through configuration files
+- **Key modifiers**: Add top labels and held-state keys to custom layouts with [key modifier objects](/docs/advanced/key-modifiers.md)
 - **Side-by-side layouts**: Display [alternative layouts](/docs/advanced/alternative-layouts.md) alongside the default layout
 - **Top row/Number row**: Optional row above the main keyboard for numbers or user-configured keys
 - **[Layer switching](/docs/advanced/layer-switching.md)**: Switch between multiple custom keyboard layers for QMK, ZMK, or other programmable keyboard firmware using configurable triggers and toggle modes
@@ -180,7 +181,6 @@ OverKeys can be installed through several methods:
    <sub>Note: Please check if `winget` version is updated to the latest version as in the repo. Otherwise, use the [installer](https://github.com/conventoangelo/OverKeys/releases/latest) to have the latest version.</sub>
 
 2. **Using the Installer**
-
    - Download and run the latest [EXE installer](https://github.com/conventoangelo/OverKeys/releases/latest).
 
 3. **Portable Version**
@@ -202,13 +202,15 @@ Complete documentation for OverKeys is available in the [docs](docs/index.md) fo
 ### User Guide
 
 - [Preferences](/docs/user-guide/preferences.md)
+- [Text Settings](/docs/user-guide/text.md)
 - [Learning Mode](/docs/user-guide/learning-mode.md)
 - [Built-in Layouts](#features)
 
 ### Advanced Features
 
 - [Custom Font](/docs/advanced/custom-font.md)
 - [Custom Layouts](/docs/advanced/custom-layouts.md)
+- [Key Modifiers](/docs/advanced/key-modifiers.md)
 - [Alternative Layouts](/docs/advanced/alternative-layouts.md)
 - [6-Column Layouts](/docs/advanced/6-column-layouts.md)
 - [Layer Switching](/docs/advanced/layer-switching.md)
@@ -223,7 +225,6 @@ Complete documentation for OverKeys is available in the [docs](docs/index.md) fo
 
 Contributions are what make the open-source community such an amazing place to learn and collaborate. Any contributions to **OverKeys** are greatly appreciated. If you have suggestions for improvements, bug fixes, or new features, please feel free to open an issue or submit a pull request. For detailed contribution guidelines, see the [CONTRIBUTING.md](.github/CONTRIBUTING.md) file.
 
-
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ## License

docs/advanced/key-modifiers.md

@@ -0,0 +1,74 @@
+# Key Modifiers
+
+OverKeys supports richer key entries inside custom layouts so you can show a top label, track a different underlying key, and keep certain keys visually held. This is useful for layer-style layouts, modifier keys, and layouts that need two labels on the same key. This was greatly inspired from the key modifier support in [caksoylar's keymap-drawer](https://github.com/caksoylar/keymap-drawer).
+
+## Overview
+
+In `userLayouts`, each key can still be a plain string. You can also use an object with these fields:
+
+- `t`: Tracked key used for key press detection and shift mapping
+- `h`: Top label shown near the top of the key
+- `type`: Optional key state hint; use `held` to keep the key rendered as pressed
+
+Plain string entries continue to work exactly as before, so you can mix both formats within the same layout.
+
+![Space as tracked key and shift as the top label.](image.png)
+*Space as tracked key and shift as the top label.*
+
+![NUM layer change key with type pressed](image-1.png)
+*NUM layer change key with type pressed*
+
+## Example
+
+```jsonc
+{
+	"userLayouts": [
+		{
+			"name": "Layer",
+			"keys": [
+				["A", { "h": "Shift", "t": "T", "type": "held" }],
+				["B", "C"],
+			],
+		},
+	],
+}
+```
+
+In this example:
+
+- `A` is rendered as a normal key
+- The second key displays `Shift` at the top and `T` as the tracked key
+- `type: "held"` keeps the key styled like it is active, useful for modifier keys or layer keys that should stay visually active
+
+## 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 **Advanced** tab
+5. Toggle **Turn on advanced settings**
+6. Toggle **Use user layouts** if you want the custom layout to be loaded
+
+### Using the Configuration File
+
+1. Right-click the OverKeys tray icon
+2. Select **Preferences**
+3. Go to the **Advanced** tab
+4. Click **Open Config**
+5. Edit the `userLayouts` array using the object form where needed
+6. Save the file
+7. Right-click the tray icon and click **Reload config** to apply changes
+
+## Behavior Notes
+
+- `t` controls the actual key OverKeys tracks for press state and alias/shift behavior
+- `h` is only visual and can be omitted when you do not need a separate top label
+- `held` is useful for modifier or layer keys that should stay visually active
+
+## Troubleshooting
+
+- If a modifier key does not display correctly, make sure the JSON object uses the exact field names `h`, `t`, and `type`
+- If the tracked key is missing, OverKeys falls back to the top label or the object value when possible
+- If the label looks cramped, adjust the text sizes in the [Text Settings](../user-guide/text.md) page

docs/index.md

@@ -1,45 +1,47 @@
-# OverKeys Documentation
-
-Welcome to the OverKeys documentation! This guide will help you get started with OverKeys, a customizable, open-source on-screen keyboard visualizer for alternative layouts.
-
-## Getting Started
-
-- [Installation](getting-started/installation.md) - Install and set up OverKeys on your Windows machine
-- [Basic Usage](getting-started/basic-usage.md) - Learn how to use OverKeys's core features
-
-## User Guide
-
-- [Preferences](user-guide/preferences.md) - Configure OverKeys to match your needs
-- [Learning Mode](user-guide/learning-mode.md) - Use the specialized color scheme for learning new layouts
-- [Supported Layouts](../README.md#features) - View the list of built-in keyboard layouts
-
-## Advanced Features
-
-- [Custom Font](advanced/custom-font.md) - Use a system-installed font not found in the dropdown
-- [Custom Layouts](advanced/custom-layouts.md) - Create and use your own keyboard layouts
-- [Alternative Layouts](advanced/alternative-layouts.md) - Quickly switch between different layouts
-- [6-Column Layouts](advanced/6-column-layouts.md) - Set up OverKeys for a 6-column split matrix keyboard
-- [Layer Switching](advanced/layer-switching.md) - Switch between multiple custom keyboard layers with custom triggers
-- [Ignored Keys](advanced/ignored-keys.md) - Prevent specific keys from triggering the keyboard overlay
-- [Kanata Integration](advanced/kanata-integration.md) - Connect OverKeys with Kanata for advanced functionality
-- [Custom Aliases](advanced/custom-aliases.md) - Define custom aliases for key combinations
-- [Shift Mappings](advanced/shift-mappings.md) - Customize shift-key behavior for specific characters
-- [Supported Keys](advanced/supported-keys.md) - Complete list of keys you can use in custom layouts
-- [Locales](advanced/locales.md) - Add locale-specific keys in user configuration for key press recognition
-
-## Additional Resources
-
-- [Project README](../README.md) - Overview of the project
-- [Changelog](../CHANGELOG.md) - Release history and features
-- [GitHub Repository](https://github.com/conventoangelo/OverKeys) - Source code and issue tracking
-
-## Common Tasks
-
-- [Creating a custom layout](advanced/custom-layouts.md#creating-custom-layouts)
-- [Setting up alternative layout switching](advanced/alternative-layouts.md)
-- [Finding key names for custom layouts](advanced/supported-keys.md)
-- [Troubleshooting custom layouts](advanced/custom-layouts.md#troubleshooting)
-
-## Support
-
-If you encounter any issues or have questions, please visit the [GitHub Discussions](https://github.com/conventoangelo/OverKeys/discussions) page or [report a bug](https://github.com/conventoangelo/OverKeys/issues/new?template=bug_report.md).
+# OverKeys Documentation
+
+Welcome to the OverKeys documentation! This guide will help you get started with OverKeys, a customizable, open-source on-screen keyboard visualizer for alternative layouts.
+
+## Getting Started
+
+- [Installation](getting-started/installation.md) - Install and set up OverKeys on your Windows machine
+- [Basic Usage](getting-started/basic-usage.md) - Learn how to use OverKeys's core features
+
+## User Guide
+
+- [Preferences](user-guide/preferences.md) - Configure OverKeys to match your needs
+- [Text Settings](user-guide/text.md) - Tune key label sizing for long labels and top labels
+- [Learning Mode](user-guide/learning-mode.md) - Use the specialized color scheme for learning new layouts
+- [Supported Layouts](../README.md#features) - View the list of built-in keyboard layouts
+
+## Advanced Features
+
+- [Custom Font](advanced/custom-font.md) - Use a system-installed font not found in the dropdown
+- [Custom Layouts](advanced/custom-layouts.md) - Create and use your own keyboard layouts
+- [Key Modifiers](advanced/key-modifiers.md) - Add top labels and held-state keys to custom layouts
+- [Alternative Layouts](advanced/alternative-layouts.md) - Quickly switch between different layouts
+- [6-Column Layouts](advanced/6-column-layouts.md) - Set up OverKeys for a 6-column split matrix keyboard
+- [Layer Switching](advanced/layer-switching.md) - Switch between multiple custom keyboard layers with custom triggers
+- [Ignored Keys](advanced/ignored-keys.md) - Prevent specific keys from triggering the keyboard overlay
+- [Kanata Integration](advanced/kanata-integration.md) - Connect OverKeys with Kanata for advanced functionality
+- [Custom Aliases](advanced/custom-aliases.md) - Define custom aliases for key combinations
+- [Shift Mappings](advanced/shift-mappings.md) - Customize shift-key behavior for specific characters
+- [Supported Keys](advanced/supported-keys.md) - Complete list of keys you can use in custom layouts
+- [Locales](advanced/locales.md) - Add locale-specific keys in user configuration for key press recognition
+
+## Additional Resources
+
+- [Project README](../README.md) - Overview of the project
+- [Changelog](../CHANGELOG.md) - Release history and features
+- [GitHub Repository](https://github.com/conventoangelo/OverKeys) - Source code and issue tracking
+
+## Common Tasks
+
+- [Creating a custom layout](advanced/custom-layouts.md#creating-custom-layouts)
+- [Setting up alternative layout switching](advanced/alternative-layouts.md)
+- [Finding key names for custom layouts](advanced/supported-keys.md)
+- [Troubleshooting custom layouts](advanced/custom-layouts.md#troubleshooting)
+
+## Support
+
+If you encounter any issues or have questions, please visit the [GitHub Discussions](https://github.com/conventoangelo/OverKeys/discussions) page or [report a bug](https://github.com/conventoangelo/OverKeys/issues/new?template=bug_report.md).