Coming from Karabiner-Elements
How Karabiner-Elements remaps, dual-role keys, layers and complex modifications map to Switchboard, and what the import keeps, notes or leaves out.
Karabiner keeps everything in one file, ~/.config/karabiner/karabiner.json. Import reads it directly (File › Import…, or switchboard import --karabiner), or a single complex-modification rule file (the JSON from the public rule gallery), which becomes one group per rule.
Nothing is enabled while Karabiner runs: its virtual keyboard would double every remap. Quit Karabiner-Elements and its menu bar agent before you turn imported items on.
What maps #
| Karabiner | Switchboard | Note |
|---|---|---|
| Simple modifications, key to key | A remap | Exact |
| Function key settings | A remap when the target is a key | A media target is dropped: macOS already sends it |
| A basic manipulator, one key to one key (with modifiers) | A remap | optional: any is how remaps already work |
Key held is a modifier, tapped is a key (to_if_alone) | A dual-role remap | Library ▸ Remaps shows it, with the tap threshold (200 ms unless the file sets one) |
| Caps Lock as Esc and Control, or Hyper | A dual-role remap on F18 | The engine maps Caps Lock to F18 while a remap listens for it |
| A held key sets a variable, other keys test it | A layer, hold mode | Karabiner's layer idiom, recognised: the Vim-arrows rule becomes a group with bare-key macros |
| A key toggles a variable and Esc clears it | A sticky layer | The off-key is dropped: Esc leaves a layer |
| Users of the variable clear it themselves | A next-key layer | |
| Other variables | A shared. variable and a variable condition | Exact |
| Several keys, shell commands, mouse keys, media keys | A macro with a hotkey trigger | pressKeys, shell, variable, moveBy, click, notify |
to_if_held_down, to_after_key_up, to_delayed_action | Hotkey macros on the long-press, release and tap phases | A delayed action always runs here: Karabiner cancels it on the next key |
| App conditions | Group scope, or the remap's app | A pattern is resolved against the apps installed now |
| Device conditions and per-device rules | Imported for every keyboard, with a note | The key tap can't tell keyboards apart |
| Non-selected profiles | Groups named after the profile, off |
What it can't do #
Modifier keys as the source (Left Option to Control): Karabiner works below the system, Switchboard's tap sees only key presses. Listed with a reason.
Simultaneous keys: there is no chord trigger. Make it a layer, or a typed sequence.
A mouse button or "any" key as the source,
sticky_modifier,select_input_source: listed, not imported.Input source, keyboard type and event-changed conditions: a script condition that is always true stands in, and the macro stays off until you edit it.
A bare key outside a layer ("J alone"): imported off, because it would swallow every J you type. Put it in a layer or add a modifier.
Secure input (a password field) holds dual-role keys and layers too.