One Key, Multiple Actions

A standard keyboard gives you about 80 keys, and each one does exactly one thing. That’s limiting — you run out of convenient shortcuts fast, especially if you want to launch apps, navigate, and use modifiers without leaving the home row.

KeyPath lets a single key do different things depending on how you press it:

  • Tap-Hold: Tap for one action, hold for another — like Caps Lock that sends Escape on tap but activates shortcuts on hold
  • Tap-Dance: Different actions for single tap, double tap, triple tap — like a double-click but for any key

These dual-role keys are the foundation of everything else in KeyPath: home row modifiers, app launching, navigation layers, and more.

If you’re new to these ideas, start with the Keyboard Concepts page for a beginner-friendly overview.

Quick Start

Creating a Tap-Hold Key

  1. Open the Custom Rules tab in the inspector panel
  2. Click New Rule (+ button)
  3. Set your Start key and Finish key (tap action)
  4. Enable the Hold, Double Tap, etc. toggle
  5. Set On Hold — this is what happens when held
  6. Choose hold behavior
  7. Save

Screenshot Screenshot — Custom Rules tab with new rule form:

  ┌─────────────────────────────────────────────────────┐
  │  Custom Rules                                       │
  │                                                     │
  │  ┌────────────────────────────────────────────────┐ │
  │  │  EVERYWHERE (global rules)                     │ │
  │  │                                                │ │
  │  │  caps_lock ──→ escape                          │ │
  │  │  a (hold) ──→ left_shift                       │ │
  │  │  f (hold) ──→ left_command                     │ │
  │  └────────────────────────────────────────────────┘ │
  │                                                     │
  │  ┌────────────────────────────────────────────────┐ │
  │  │  🧭 SAFARI (app-specific rules)                │ │
  │  │                                                │ │
  │  │  h ──→ left_arrow                              │ │
  │  │  j ──→ down_arrow                              │ │
  │  │  k ──→ up_arrow                                │ │
  │  │  l ──→ right_arrow                             │ │
  │  └────────────────────────────────────────────────┘ │
  │                                                     │
  │  [ ↺ Reset ]                     [ + New Rule ]     │
  └─────────────────────────────────────────────────────┘

Screenshot Screenshot — Rule editor with hold behavior options:

  ┌─────────────────────────────────────────────────────┐
  │  New Rule                                           │
  │                                                     │
  │  Start key:    [ caps_lock      ▾ ]                 │
  │  Finish key:   [ escape         ▾ ]  (tap action)   │
  │                                                     │
  │  ┌ Hold, Double Tap, etc. ─────────────── [ON] ──┐ │
  │  │                                                │ │
  │  │  On Hold:   [ left_control   ▾ ]               │ │
  │  │                                                │ │
  │  │  Hold Behavior:                                │ │
  │  │  ┌──────────┐ ┌──────────┐ ┌──────────┐       │ │
  │  │  │  Basic   │ │ Trigger  │ │  Quick   │       │ │
  │  │  │          │ │  early   │ │   tap    │       │ │
  │  │  └──────────┘ └──────────┘ └──────────┘       │ │
  │  │                                                │ │
  │  │  Tap timeout:   [ 200 ms ]                     │ │
  │  │  Hold timeout:  [ 200 ms ]                     │ │
  │  └────────────────────────────────────────────────┘ │
  │                                                     │
  │                              [ Cancel ]  [ Save ]   │
  └─────────────────────────────────────────────────────┘

Creating a Tap-Dance Key

  1. Open the Custom Rules tab in the inspector panel
  2. Click New Rule (+ button)
  3. Set your Start key (e.g., caps)
  4. Set your Finish key (e.g., esc) — this is the single-tap action
  5. Enable Hold, Double Tap, etc. toggle
  6. Set Double Tap (e.g., caps)
  7. (Optional) Click Add Tap Step for triple-tap, quad-tap, etc.
  8. Save

Note: Hold and Tap-Dance cannot be used together on the same key. If you try to set one when the other is already configured, a dialog will ask which behavior you want to keep.

Hold Behavior Options

Option Description Kanata Variant
Basic Hold activates after timeout tap-hold
Trigger early Hold activates when another key is pressed tap-hold-press
Quick tap Fast taps always register as tap tap-hold-release
Custom keys Only specific keys trigger early tap tap-hold-release-keys

Common Use Cases

Home Row Modifiers

Map your home row keys to modifiers when held:

a → a (tap) / Left Control (hold)
s → s (tap) / Left Shift (hold)
d → d (tap) / Left Alt (hold)
f → f (tap) / Left Command (hold)

Settings:

  • Hold behavior: Trigger early
  • Tap timeout: 200ms
  • Hold timeout: 200ms

This allows you to press a + j quickly and it triggers Ctrl+J instead of aj.

Caps Lock Replacement

Replace Caps Lock with Escape on tap, Control on hold:

caps → esc (tap) / lctl (hold)

Settings:

  • Hold behavior: Basic
  • Tap timeout: 200ms

Space Cadet Shift

Space bar that acts as Space on tap, Shift on hold:

spc → spc (tap) / lsft (hold)

Settings:

  • Hold behavior: Quick tap
  • Tap timeout: 200ms

Tap-Dance Examples

Escape / Caps Lock / Control

caps → esc (single tap) / caps (double tap) / lctl (triple tap)

Function Key Layer Toggle

f1 → f1 (single tap) / layer-toggle function (double tap)

Technical Details

Kanata Variants

KeyPath generates the appropriate Kanata variant based on your settings:

  1. tap-hold-press: Hold triggers on other key press (activateHoldOnOtherKey = true)
  2. tap-hold-release: Quick-tap / permissive-hold (quickTap = true)
  3. tap-hold-release-keys: Early tap on specific keys (customTapKeys non-empty)
  4. tap-hold: Basic timeout-based (default)

Timeout Configuration

  • Tap timeout: Time (ms) before hold activates
  • Hold timeout: Time (ms) for hold to fully activate

Default is 200ms for both, which works well for most users. Adjust based on your typing speed and preferences.

Troubleshooting

Hold activates too quickly

Increase the tap timeout. Try 250ms or 300ms.

Hold doesn’t activate reliably

  • Use Trigger early for home-row mods
  • Decrease hold timeout
  • Check for conflicts with other remappings

Tap-Dance not working

Ensure you’ve set at least a double-tap action. Single tap alone won’t enable tap-dance behavior.

Advanced Configuration

For power users, you can edit the generated Kanata config directly to fine-tune behavior. See the Kanata tap-hold documentation for all available options.

Next Steps

External resources