Skip to content

Latest commit

 

History

History
2384 lines (1898 loc) · 70.3 KB

config.adoc

File metadata and controls

2384 lines (1898 loc) · 70.3 KB
Raw

Configuration

This document describes how to create a kanata configuration file. The kanata configuration file will determine your keyboard behaviour upon running kanata.

The configuration file uses S-expression syntax from Lisps. If you are not familiar with any Lisp-like programming language, do not be too worried. This document will hopefully be a sufficient guide to help you customize your keyboard behaviour to your exact liking.

If you have any questions or confusions, feel free to file an issue or start a discussion. If you have ideas for how to improve this document or any other part of the project, please be welcome to make a pull request or file an issue.

Table of contents

Forcefully exit kanata

Though this isn’t configuration-related, it may be important for you to know that pressing and holding all of the three following keys together at the same time will cause kanata to exit:

  • Left Control

  • Space

  • Escape

This mechanism works on the key input before any remappings done by kanata.

Comments

You can add comments to your configuration file. Comments are prefixed with two semicolons. E.g:

;; This is a comment in a kanata configuration file.
;; Comments will be ignored and are intended for you to help understand your
;; own configuration when reading it later.

You can begin a multi-line comment block with #| and end it with |#:

#|
This is
a multi-line comment block
|#

Required configuration entries

defsrc

Your configuration file must have exactly one defsrc entry. This defines the order of keys that the deflayer entries will operate on.

A defsrc entry is composed of defsrc followed by key names that are separated by whitespace.

It should be noted that the defsrc entry is treated as a long sequence; the amount of whitespace (spaces, tabs, newlines) are not relevant. You may use spaces, tabs, or newlines however you like to visually format defsrc to your liking.

The primary source of all key names are the str_to_oscode and default_mappings functions in the source. Please feel welcome to file an issue if you’re unable to find the key you’re looking for.

An example defsrc containing the US QWERTY keyboard keys as an approximately 60% keyboard layout:

(defsrc
  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
  caps a    s    d    f    g    h    j    k    l    ;    '    ret
  lsft z    x    c    v    b    n    m    ,    .    /    rsft
  lctl lmet lalt           spc            ralt rmet rctl
)

Note that some keyboards have a Compose/Menu key instead of a right Meta key. In this case you can use comp instead of rmet.

For non-US keyboards, see this section.

deflayer

Your configuration file must have at least one deflayer entry. This defines how each physical key mapped in defsrc behaves when kanata runs.

A deflayer configuration entry is followed by the layer name then a list of keys or actions. The usable key names are the same as in defsrc. Actions are explained further on in this document. The whitespace story is the same as with defsrc. The order of keys/actions in deflayer corresponds to the physical key in the same sequence position defined in defsrc.

The first layer defined in your configuration file will be the starting layer when kanata runs. Other layers can be temporarily activated or switched to using actions. There is currently a maximum of 25 layers allowed.

An example defsrc and deflayer that remaps QWERTY to the Dvorak layout would be:

(defsrc
  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
  caps a    s    d    f    g    h    j    k    l    ;    '    ret
  lsft z    x    c    v    b    n    m    ,    .    /    rsft
  lctl lmet lalt           spc            ralt rmet rctl
)

(deflayer dvorak
  grv  1    2    3    4    5    6    7    8    9    0    [    ]    bspc
  tab  '    ,    .    p    y    f    g    c    r    l    /    =    \
  caps a    o    e    u    i    d    h    t    n    s    -    ret
  lsft ;    q    j    k    x    b    m    w    v    z    rsft
  lctl lmet lalt           spc            ralt rmet rctl
)

Review of required configuration entries

If you’re reading in order, you have now seen all of the required entries:

  • defsrc

  • deflayer

An example minimal configuration is:

(defsrc a b c)

(deflayer start 1 2 3)

This will make kanata remap your a b c keys to 1 2 3. This is almost certainly undesirable but is a valid configuration.

Non-US keyboards

For non-US keyboard users, you may have some keys on your keyboard with characters that are not allowed in defsrc by default, at least according to the symbol shown. You can use deflocalkeys to define additional key names that can be used in defsrc, deflayer and anywhere else in the configuration.

There are four variants of deflocalkeys:

  • deflocalkeys-win

  • deflocalkeys-wintercept

  • deflocalkeys-linux

  • deflocalkeys-macos

Only one of each deflocalkeys-* variant is allowed. The variants that are not applicable will be ignored, e.g. deflocalkeys-linux and deflocalkeys-wintercept are both ignored when using the default Windows kanata binary.

You can find configurations that others have made in this document. If you do not see your keyboard there and are not confident in using the available tools, please feel welcome to ask for help in a discussion or issue. Please contribute to the document if you are able!

Example:
(deflocalkeys-win
  ì 187
)

(deflocalkeys-wintercept
  ì 187
)

(deflocalkeys-linux
  ì 13
)

(deflocalkeys-macos
  ì 13
)

(defsrc
  grv  1    2    3    4    5    6    7    8    9    0    -    ì    bspc
)

The number used for a custom key represents the converted value for an OsCode in base 10. This differs between Windows-hooks, Windows-interception, and Linux.

In Linux, evtest will give the correct number for the physical key you press.

In Windows using the default hook mechanism, the non-interception version of the keyboard tester in the kanata repository will give the correct number. (prebuilt binary)

In Windows using Interception, the interception version of the keyboard tester will give the correct number. Between the hook and interception versions, some keys may agree but others may not; do be aware that they are not compatible!

Ideas for improving the user-friendliness of this system are welcome! As mentioned before, please ask for help in an issue or discussion if needed, and help with this document is very welcome so that future users can have an easier time 🙂.

Optional defcfg entries

defcfg

Your configuration file may include a single defcfg entry.

It can be empty but there are options that can change kanata’s behaviour that will be described in this section.

Example:
(defcfg)

process-unmapped-keys

Enabling this configuration makes kanata process keys that are not in defsrc. This is useful if you are only mapping a few keys in defsrc instead of most of the keys on your keyboard.

Without this, some actions like rpt, tap-hold-release, one-shot, will not work correctly for subsequent key presses that are not in defsrc.

This is disabled by default. The reason this is not enabled by default is because some keys may not work correctly if they are intercepted. For example, see the Windows only: windows-altgr option below.

Example:
(defcfg
  process-unmapped-keys yes
)

danger-enable-cmd

This option can be used to enable the cmd action in your configuration. The cmd action allows kanata to execute programs with arguments passed to them.

This requires using a kanata program that is compiled with the cmd action enabled. The reason for this is so that if you choose to, there is no way for kanata to execute arbitrary programs even if you download some random configuration from the internet.

This configuration is disabled by default and can be enabled by giving it the value yes.

Example:
(defcfg
  danger-enable-cmd yes
)

sequence-timeout

This option customizes the key sequence timeout (unit: ms). Its default value is 1000. The purpose of this item is explained in Sequences.

Example:
(defcfg
  sequence-timeout 2000
)

sequence-input-mode

This option customizes the key sequence input mode. Its default value when not configured is hidden-suppressed.

The options are:

  • visible-backspaced: types sequence characters as they are inputted. The typed characters will be erased with backspaces for a valid sequence termination.

  • hidden-suppressed: hides sequence characters as they are typed. Does not output the hidden characters for an invalid sequence termination.

  • hidden-delay-type: hides sequence characters as they are typed. Outputs the hidden characters for an invalid sequence termination either after a timeout or after a non-sequence key is typed.

For visible-backspaced and hidden-delay-type, a sequence leader input will be ignored if a sequence is already active. For historical reasons, and in case it is desired behaviour, a sequence leader input using hidden-suppressed will reset the key sequence.

See Sequences for more about sequences.

Example:
(defcfg
  sequence-input-mode visible-backspaced
)

sequence-backtrack-modcancel

This option customizes the behaviour of key sequences when modifiers are used. The default is yes and can be overridden to no if desired.

Setting it to yes allows both fk1 and fk2 to be activated in the following configuration, but with no, fk1 will be impossible to activate

(defseq
  fk1 (lsft a b)
  fk2 (S-(c d))
)

See Sequences for more about sequences and this document for more context about this specific configuration.

Example:
(defcfg
  sequence-backtrack-modcancel no
)

log-layer-changes

By default, kanata will log layer changes. However, logging has some processing overhead. If you do not care for the logging, you can choose to disable it.

Example:
(defcfg
  log-layer-changes no
)

delegate-to-first-layer

By default, transparent keys on layers will delegate to the corresponding defsrc key when found on a layer activated by layer-switch.

This config entry changes the behaviour to delegate to the action in the same position on the first layer defined in the configuration, which is the active layer on startup.

For more context, see jtroo#435.

Example:
(defcfg
  delegate-to-first-layer yes
)

movemouse-inherit-accel-state

By default movemouse-accel actions will track the acceleration state for vertical and horizontal axes separately.

When this setting is enabled, movemouse-accel will behave exactly like mouse movements in QMK, i.e. the acceleration state of new mouse movement actions will be inherited if others are already being pressed.

Example:
(defcfg
  movemouse-inherit-accel-state yes
)

movemouse-smooth-diagonals

By default, mouse movements move one direction at a time and vertical/horizontal movements are on independent timers.

This can result in non-smooth diagonals when drawing a line in some app. This option adds a small imperceptible amount of latency to synchronize the mouse movements.

Example:
(defcfg
  movemouse-smooth-diagonals yes
)

dynamic-macro-max-presses

This configuration allows you to customize the length limit on dynamic macros. The default length limit is 128 keys.

Example:
(defcfg
  dynamic-macro-max-presses 1000
)

concurrent-tap-hold

This configuration makes multiple tap-hold actions that are activated near in time expire their timeout quicker. By default this is disabled. When disabled, the timeout for a following tap-hold will start from 0ms after the previous tap-hold expires. When enabled, the timeout will start as soon as the tap-hold action is pressed even if a previous tap-hold action is still held and has not expired.

concurrent-tap-hold yes

Linux only: linux-dev

Back to ToC By default, kanata will try to detect which input devices are keyboards and try to intercept them all. However, you may specify exact keyboard devices from the /dev/input directories using the linux-dev configuration.

Example:
(defcfg
  linux-dev /dev/input/by-path/platform-i8042-serio-0-event-kbd
)

If you want to specify multiple keyboards, you can separate the paths with a colon :.

Example:
(defcfg
  linux-dev /dev/input/dev1:/dev/input/dev2
)

Due to using the colon to separate devices, if you have a device with colons in its file name, you must escape those colons with backslashes:

(defcfg
  linux-dev /dev/input/path-to\:device
)

Alternatively, you can use list syntax, where both backslashes and colons are parsed literally. List items are separated by spaces or newlines. Using quotation marks for each item is optional, and only required if an item contains spaces.

(defcfg
  linux-dev (
    /dev/input/path:to:device
    "/dev/input/path to device"
  )
)

Linux only: linux-dev-names-include

In the case that linux-dev is omitted, this option defines a list of device names that should be included. Device names that do not exist in the list will be ignored. This option is parsed identically to linux-dev.

Kanata will print device names on startup with log lines that look like below:

registering /dev/input/eventX: "Name goes here"
Example:
(defcfg
  linux-dev-names-include (
    "Device name 1"
    "Device name 2"
  )
)

Linux only: linux-dev-names-exclude

In the case that linux-dev is omitted, this option defines a list of device names that should be excluded. This option is parsed identically to linux-dev.

The linux-dev-names-include and linux-dev-names-exclude options are not mutually exclusive but in practice it probably only makes sense to use one and not both.

Example:
(defcfg
  linux-dev-names-exclude (
    "Device Name 1"
    "Device Name 2"
  )
)

Linux only: linux-continue-if-no-devs-found

By default, kanata will crash if no input devices are found. You can change this behaviour by setting linux-continue-if-no-devs-found.

Example:
(defcfg
  linux-continue-if-no-devs-found yes
)

Linux only: linux-unicode-u-code

Unicode on Linux works by pressing Ctrl+Shift+U, typing the unicode hex value, then pressing Enter. However, if you do remapping in userspace, e.g. via xmodmap/xkb, the keycode "U" that kanata outputs may not become a keysym "u" after the userspace remapping. This will be likely if you use non-US, non-European keyboards on top of kanata. For unicode to work, kanata needs to use the keycode that outputs the keysym "u", which might not be the keycode "U".

You can use evtest or kanata --debug, set your userspace key remapping, then press the key that outputs the keysym "u" to see which underlying keycode is sent. Then you can use this configuration to change kanata’s behaviour.

Example:
(defcfg
  linux-unicode-u-code v
)

Linux only: linux-unicode-termination

Unicode on Linux terminates with the Enter key by default. This may not work in some applications. The termination is configurable with the following options:

  • enter

  • space

  • enter-space

  • space-enter

Example:
(defcfg
  linux-unicode-termination space
)

Linux only: linux-x11-repeat-delay-rate

On Linux, you can tell kanata to run xset r rate <delay> <rate> on startup and on live reload via the configuration item linux-only-x11-repeat-rate. This takes two numbers separated by a comma. The first number is the delay in ms and the second number is the repeat rate in repeats/second.

This configuration item does not affect Wayland or no-desktop environments.

Example:
(defcfg
  linux-x11-repeat-delay-rate 400,50
)

macOS only: macos-dev-names-include

This option defines a list of device names that should be included. By default, kanata will try to detect which input devices are keyboards and try to intercept them all. However, you may specify exact keyboard devices to intercept using the macos-dev-names-include configuration. Device names that do not exist in the list will be ignored. This option is parsed identically to linux-dev.

Use kanata -l or kanata --list to list the available keyboards.

Example:
(defcfg
  macos-dev-names-include (
    "Device name 1"
    "Device name 2"
  )
)

Windows only: windows-altgr

There is an option for Windows to help mitigate the strange behaviour of AltGr (ralt) if you’re using that key in your defsrc. This is applicable for many non-US layouts. You can use one of the listed values to change what kanata does with the key:

  • cancel-lctl-press

    • This will remove the lctl press that is generated alonside ralt

  • add-lctl-release

    • This adds an lctl release when ralt is released

Example:
(defcfg
  windows-altgr add-lctl-release
)

For more context, see: jtroo#55.

Note
 Even with these workarounds, putting lctl`+ralt` in your defsrc may not work properly with other applications that also use keyboard interception. Known application with issues: GWSL/VcXsrv

Windows only: windows-interception-mouse-hwid

This defcfg item allows you to intercept mouse buttons for a specific mouse device. This only works with the Interception driver (the -wintercept variants of the binary).

The intended use case for this is for laptops such as a Thinkpad, which have mouse buttons that may be desirable to activate kanata actions with.

To know what numbers to put into the string, you can run the variant with this defcfg item defined with any numbers. Then when a button is first pressed on the mouse device, kanata will print its hwid in the log; you can then copy-paste that into this configuration entry. If this defcfg item is not defined, the log will not print.

Example:
(defcfg
  windows-interception-mouse-hwid "70, 0, 60, 0"
)

Using multiple defcfg entries

The defcfg entry is treated as a list with pairs of strings. For example:

(defcfg a 1 b 2)

This will be treated as configuration a having value 1 and configuration b having value 2.

An example defcfg containing many of the options is shown below. It should be noted options that are Linux-only, Windows-only, or macOS-only will be ignored when used on a non-applicable operating system.

;; Don't actually use this exact configuration,
;; it's almost certainly not what you want.
(defcfg
  process-unmapped-keys yes
  danger-enable-cmd yes
  sequence-timeout 2000
  sequence-input-mode visible-backspaced
  sequence-backtrack-modcancel no
  log-layer-changes no
  delegate-to-first-layer yes
  movemouse-inherit-accel-state yes
  movemouse-smooth-diagonals yes
  dynamic-macro-max-presses 1000
  linux-dev (/dev/input/dev1 /dev/input/dev2)
  linux-dev-names-include ("Name 1" "Name 2")
  linux-dev-names-exclude ("Name 3" "Name 4")
  linux-continue-if-no-devs-found yes
  linux-unicode-u-code v
  linux-unicode-termination space
  linux-x11-repeat-delay-rate 400,50
  windows-altgr add-lctl-release
  windows-interception-mouse-hwid "70, 0, 60, 0"
)

Aliases and variables

Before learning about actions, it will be useful to first learn about aliases and variables.

Aliases

Using the defalias configuration entry, you can introduce a shortcut label for an action.

Similar to how defcfg works, defalias reads pairs of items in a sequence where the first item in the pair is the alias name and the second item is the action it can be substituted for. However, unlike defcfg, the second item in defalias may be a "list" as opposed to a single string like it was in defcfg.

A list is a sequence of strings separated by whitespace, surrounded by parentheses. All of the configuration entries we’ve looked at so far are lists; defalias is where we’ll first see nested lists in this guide.

Example:
(defalias
  ;; tap for caps lock, hold for left control
  cap (tap-hold 200 200 caps lctl)
)

This alias can be used in deflayer as a substitute for the long action. The alias name is prefixed with @ to signify that it’s an alias as opposed to a normal key.

(deflayer example
  @cap a s d f
)

You may have multiple defalias entries and multiple aliases within a single defalias. Aliases may also refer to other aliases that were defined earlier in the configuration file.

Example:
(defalias one (tap-hold 200 200 caps lctl))
(defalias two (tap-hold 200 200 esc lctl))
(defalias
  three C-A-del ;; Ctrl+Alt+Del
  four (tap-hold 200 200 @three ralt)
)

You can choose to put actions without aliasing them right into deflayer. However, for long actions it is recommended not to do so to keep a nice visual alignment. Visually aligning your deflayer entries will hopefully make your configuration file easier to read.

Example:
(deflayer example
  ;; this is equivalent to the previous deflayer example
  (tap-hold 200 200 caps lctl) a s d f
)

Variables

Using the defvar configuration entry, you can introduce a shortcut label for an arbitrary string or list. Unlike an alias, a variable does not need to be a valid standalone action. In other words, a variable can be used as components of actions.

The most common use case is to define common number strings for actions such as tap-hold, tap-dance, and one-shot.

Similar to how defalias works, defvar reads pairs of items in a sequence where the first item in the pair is the variable name and the second item is a string or list. Variables are allowed to refer to previously defined variables.

Variables can be used to substitute most values. Some notable exceptions are:

  • variables cannot be used in defcfg, defsrc, or deflocalkeys

  • variables cannot be used to substitute a layer name

  • variables cannot be used to substitute an action name

Variables are referred to by prefixing their name with $.

Example:
(defvar
  tap-timeout   100
  hold-timeout  200
  tt $tap-timeout
  ht $hold-timeout
)

(defalias
  th1 (tap-hold $tt $ht caps lctl)
  th2 (tap-hold $tt $ht spc  lsft)
)

Actions

The actions kanata provides are what make it truly customizable. This section explains the available actions.

Live reload

You can put the lrld action onto a key to live-reload your configuration file. If kanata can’t parse the file, it will continue using the previous configuration.

Example:
(deflayer has-live-reload
  lrld a s d f
)

There are variants of lrld: lrld-prev and lrld-next. These will cycle through different configuration files that you specify on kanata’s startup. The first configuration file specified will be the one loaded on startup. The prev/next variants can be used with shortened names of lrpv and lrnx as well.

Example:
(deflayer has-live-reloads
  lrld lrpv lrnx
)

Example specifying multiple config files in the command line:

kanata -c startup.cfg -c 2nd.cfg -c 3rd.cfg

layer-switch

This action allows you to switch to another "base" layer. This is permanent until a layer-switch to another layer is activated. The concept of a base layer makes more sense when looking at the next action: layer-while-held.

This action accepts a single subsequent string which must be a layer name defined in a deflayer entry.

Example:
(defalias dvk (layer-switch dvorak))

layer-while-held

This action allows you to temporarily change to another layer while the key remains held. When the key is released, you go back to the currently active "base" layer.

This action accepts a single subsequent string which must be a layer name defined in a deflayer entry.

Example:
(defalias nav (layer-while-held navigation))

You may also use layer-toggle in place of layer-while-held; they behave exactly the same. The layer-toggle name is slightly shorter but is a bit inaccurate with regards to its meaning.

Transparent key

If you use a single underscore for a key _ then it acts as a "transparent" key in a deflayer. The behaviour depends if _ is on a base layer or a while-held layer. When _ is pressed on the active base layer, the key will default to the corresponding defsrc key. If _ is pressed on the active while-held layer, the base layer’s behaviour will activate.

Example:
(defsrc
  a b c
)

(deflayer remap-only-c-to-d
  _ _ d
)

No-op

You may use the action XX as a "no operation" key, meaning pressing the key will do nothing. This might be desirable in place of a transparent key on a layer that is not fully mapped so that a key that is intentionally not mapped will do nothing as opposed to typing a letter.

Example:
(deflayer contains-no-op
  XX a s d f
)

Unicode

The unicode action accepts a single unicode character. The character will not be repeatedly typed if you hold the key down.

You may use a unicode character as an alias if desired.

Note
 The unicode action may not be correctly accepted by the active application.
Note
 If using Linux, make sure to look at the unicode behaviour customization in defcfg. 
(defalias
  sml (unicode 😀)
  🙁 (unicode 🙁)
)
(deflayer has-happy-sad
  @sml @🙁 a s d f
)

Output chords/combos

You may want to remap a key to automatically be pressed in combination with modifiers such as Control or Shift. You can achieve this by prefixing the normal key name with one or more of:

  • C-: Left Control

  • A-: Left Alt

  • S-: Left Shift

  • M-: Left Meta, a.k.a. Windows, GUI, Command, Super

  • RA- or AG: Right Alt, a.k.a. AltGr

These modifiers may be combined together if desired.

Example:
(defalias
  ;; Type exclamation mark (US layout)
  ex! S-1
  ;; Ctrl+C: send SIGINT to a Linux terminal program
  int C-c
  ;; Win+Tab: open Windows' Task View
  tsk M-tab
  ;; Ctrl+Shift+(C|V): copy or paste from certain terminal programs
  cpy C-S-c
  pst C-S-v
)

A special behaviour of output chords is that if another key is pressed, all of the chord keys will be released before the newly pressed key action activates. Output chords are typically used do one-off actions such as:

  • type a symbol, e.g. S-1

  • type a special/accented character, e.g. RA-a

  • do a special action like C-c to send SIGTERM in the terminal

The modifier pressed with these one-off action is usually not desired for subsequent actions.

Repeat key

The action rpt repeats the most recently typed key. Holding down this key will not repeatedly send the key. The intended use case is to be able to use a different finger or even thumb key to repeat a typed key, as opposed to double-tapping a key.

Example:
(deflayer has-repeat
  rpt a s d f
)

The rpt action only repeats the last key output. For example, it won’t output a chord like ctrl+c if the previous key pressed was C-c. The rpt action will only output c in this case.

There is a variant rpt-any which will repeat any previous action and would output ctrl+c in the example case.

(deflayer has-repeat-any
  rpt-any a s d f
)

Release a key or layer

You can release a held key or layer via these actions:

  • release-key: release a key, accepts defsrc compatible names

  • release-layer: release a while-held layer

An example practical use case for release-key is seen in the multi section directly below.

There is currently no known practical use case for release-layer, but it exists nonetheless.

multi

The multi action executes multiple keys or actions in order but also simultaneously. It accepts one or more actions.

An example use case is to press the "Alt" key while also activating another layer.

In the example below, holding the physical "Alt" key will result in a held layer being activated while also holding "Alt" itself. The held layer operates nearly the same as the standard keyboard, so for example the sequence (hold Alt)+(Tab+Tab+Tab) will work as expected. This is in contrast to having a layer where tab is mapped to A-tab, which results in repeated press+release of the two keys and has different behaviour than expected. Some special keys will release the "Alt" key and do some other action that requires "Alt" to be released. In other words, the "Alt" key serves a dual purpose of still fulfilling the "Alt" key role for some button presses (e.g. Tab), but also as a new layer for keys that aren’t typically used with "Alt" to have added useful functionality.

(defalias
  atl (multi alt (layer-while-held alted-with-exceptions))
  lft (multi (release-key alt) left) ;; release alt if held and also press left
  rgt (multi (release-key alt) rght) ;; release alt if held and also press rght
)

(defsrc
  alt  a    s    d    f
)

(deflayer base
  @atl _    _    _    _
)

(deflayer alted-with-exceptions
  _    _    _    @lft @rgt
)
Warning
 This action can sometimes behave in surprising ways with regards to simultaneity and order of actions. For example, an action like (multi sldr ') will not behave as expected. Due to implementation details, sldr will activate after the ' even though it is listed before. This example could instead be written as (macro sldr 10 '), and that would work as intended. It is recommended to avoid multi if it can be replaced with a different action like macro or an output chord.

Mouse actions

You can click the left, middle, and right buttons using kanata actions, do vertical/horizontal scrolling, and move the mouse.

Mouse buttons

The mouse button actions are:

  • mlft: left mouse button

  • mmid: middle mouse button

  • mrgt: right mouse button

  • mfwd: forward mouse button

  • mbck: backward mouse button

The mouse button will be held while the key mapped to it is held.

If there are multiple mouse click actions within a single multi action, e.g.

(multi mrgt mlft)

then all the buttons except the last will be clicked then unclicked. The last button will remain held until key release. In the example above, pressing then releasing the key mapped to this action will result in the following event sequence:

  1. press key mapped to multi

  2. click right mouse button

  3. unclick right mouse button

  4. click left mouse button

  5. release key mapped to multi

  6. release left mouse button

There are variants of the standard mouse buttons which "tap" the button. Rather than holding the button while the key is held, a mouse click will be immediately followed by the release. Nothing happens when the key is released. The actions are as follows:

  • mltp: tap left mouse button

  • mmtp: tap middle mouse button

  • mrtp: tap right mouse button

  • mftp: tap forward mouse button

  • mbtp: tap bacward mouse button

Mouse wheel

The mouse wheel actions are:

  • mwheel-up: vertical scroll up

  • mwheel-down: vertical scroll down

  • mwheel-left: horizontal scroll left

  • mwheel-right: horizontal scroll right

All of these actions accept two number strings. The first is the interval (unit: ms) between scroll actions. The second number is the distance (unit: arbitrary). In both Windows and Linux, 120 distance units is equivalent to a notch movement on a physical wheel. You can play with the parameters to see what feels correct to you. Both numbers must be in the range [1,65535].

Note
 In Linux, not all desktop environments support the REL_WHEEL_HI_RES event. If this is the case for yours, it will likely be a better experience to use a distance value that is a multiple of 120.

On Linux and Interception, you can also choose to read from a mouse device. When doing so, using the mwu, mwd, mwl, mwr key names in defsrc allow you to remap the mouse scroll up/down/left/right actions like you would with keyboard keys.

Note
 If you are using a high-resolution mouse in Linux, only a full "notch" of the scroll wheel will activate the action.
Note
 If you are using a high-resolution mouse with Interception, you will probably get way more events than you intended.

Mouse movement

The mouse movement actions are:

  • movemouse-up

  • movemouse-down

  • movemouse-left

  • movemouse-right

Similar to the mouse wheel actions, all of these actions accept two number strings. The first is the interval (unit: ms) between movement actions and the second number is the distance (unit: pixels) of each movement.

The following are variants of the above mouse movements that apply linear mouse acceleration from the minimum distance to the maximum distance as the mapped key is held.

  • movemouse-accel-up

  • movemouse-accel-down

  • movemouse-accel-left

  • movemouse-accel-right

All these actions accept four number strings. The first number is the interval (unit: ms) between movement actions. The second number is the time it takes (unit: ms) to linearly ramp up from the minimum distance to the maximum distance. The third and fourth numbers are the minimum and maximum distances (unit: pixels) of each movement.

There is a toggable defcfg option related to movemouse-accel - movemouse-inherit-accel-state. You might want to enable it, especially if you’re coming from QMK.

Set absolute mouse position

The action setmouse sets the absolute mouse position.

Warning
 This is only supported in Windows right now. For an interesting keyboard-centric mouse solution in Linux, try looking at warpd.

This list action takes two parameters which are x and y positions of the absolute movement. The values go from 0,0 which is the upper-left corner of the screen to 65535,65535 which is the lower-right corner of the screen. If you have multiple monitors, setmouse treats them all as a single large screen. This can make it a little confusing for how to set the x, y values to get the positions that you want. Experimentation will be needed.

Modify the speed of mouse movements

The action movemouse-speed modifies the speed at which movemouse and movemouse-accel function at runtime. It does this by expanding or shrinking min_distance and max_distance while the action key is pressed.

This action accepts one number (unit: percentage) by which the mouse movements will be accelerated.

Warning
 Due to the nature of pixels being whole numbers, some values such as 33 may not result in an exact third of the distance.
Example:
(defalias
  fst (movemouse-speed 200)
  slw (movemouse-speed 50)
)

Mouse all actions example

(defalias
  mwu (mwheel-up 50 120)
  mwd (mwheel-down 50 120)
  mwl (mwheel-left 50 120)
  mwr (mwheel-right 50 120)

  ms↑ (movemouse-up 1 1)
  ms← (movemouse-left 1 1)
  ms↓ (movemouse-down 1 1)
  ms→ (movemouse-right 1 1)

  ma↑ (movemouse-accel-up 1 1000 1 5)
  ma← (movemouse-accel-left 1 1000 1 5)
  ma↓ (movemouse-accel-down 1 1000 1 5)
  ma→ (movemouse-accel-right 1 1000 1 5)

  sm (setmouse 32228 32228)

  fst (movemouse-speed 200)
)

(deflayer mouse
  _    @mwu @mwd @mwl @mwr _    _    _    _    _    @ma↑ _    _    _
  _    pgup bck  _    fwd  _    _    _    _    @ma← @ma↓ @ma→ _    _
  _    pgdn mlft _    mrgt mmid _    mbck mfwd _    @ms↑ _    _
  @fst _    mltp _    mrtp mmtp _    mbtp mftp @ms← @ms↓ @ms→
  _    _    _              _              _    _    _
)

tap-dance

The tap-dance action allows repeated tapping of a key to result in different actions. It is followed by a timeout (unit: ms) and a list of keys or actions. Each time the key is pressed, its timeout will reset. The action will be chosen if one of the following events occur:

  • the timeout expires

  • a different key is pressed

  • the key is repeated up to the final action

You may put normal keys or other actions in tap-dance.

Example:
(defalias
  ;; 1 tap : "A" key
  ;; 2 taps: Control+C
  ;; 3 taps: Switch to another layer
  ;; 4 taps: Escape key
  td (tap-dance 200 (a C-c (layer-switch l2) esc))
)

There is a variant of tap-dance with the name tap-dance-eager. The variant is parsed identically but the difference is that it will activate every action in the sequence as the taps progress.

In the example below, repeated taps will, in order:

  1. type a

  2. erase the a and type bb

  3. erase the bb and type ccc

(defalias
  td2 (tap-dance-eager 500 (
    (macro a) ;; use macro to prevent auto-repeat of the key
    (macro bspc b b)
    (macro bspc bspc c c c)
  ))
)

one-shot

The one-shot action is similar to "sticky keys", if you know what that is. This activates an action or key until either the timeout expires or a different key is used. The one-shot action must be followed by a timeout (unit: ms) and another key or action.

Some of the intended use cases are:

  • press a modifier for exactly one following key press

  • switch to another layer for exactly one following key press

If a one-shot key is held then it will act as the regular key. E.g. holding a key assigned with @os1 in the example below will keep Left Shift held for every key, not just one, as long as it’s still physically pressed.

Pressing multiple one-shot keys in a row within the timeout will combine the actions of those keys and reset the timeout to the value of the most recently pressed one-shot key.

There are four variants of the one-shot action:

  • one-shot-press: end on the first press of another key

  • one-shot-release: end on the first release of another key

  • one-shot-press-pcancel: end on the first press of another key or on re-press of another active one-shot key

  • one-shot-release-pcancel: end on the first release of another key or on re-press of another active one-shot key

It is important to note that the first activation of a one-shot key determines the behaviour with regards to the 4 variants for all subsequent one-shot key activations, even if a following one-shot key has a different configuration than the initial key pressed.

The default name one-shot corresponds to one-shot-press.

Example:
(defalias
  os1 (one-shot 500 (layer-while-held another-layer))
  os2 (one-shot-press 2000 lsft)
  os3 (one-shot-release 2000 lctl)
  os4 (one-shot-press-pcancel 2000 lalt)
  os5 (one-shot-release-pcancel 2000 lmet)
)

tap-hold

Warning
 The tap-hold action and all variants can behave unexpectedly on Linux with respect to repeat of antecedent key presses. The full context is in discussion #422. In brief, the workaround is to use tap-hold inside of multi, combined with another key action that behaves as a no-op like f24.
Example: (multi f24 (tap-hold …​))

The tap-hold action allows you to have one action/key for a "tap" and a different action/key for a "hold". A tap is a rapid press then release of the key whereas a hold is a long press.

The action takes 4 parameters in the listed order:

  1. tap timeout (unit: ms)

  2. hold timeout (unit: ms)

  3. tap action

  4. hold action

The tap timeout is the number of milliseconds within which a rapid press+release+press of a key will result in the tap action being held instead of the hold action activating.

The hold timeout is the number of milliseconds after which the hold action will activate.

There are two additional variants of tap-hold:

  • tap-hold-press

    • If there is a press of a different key, the hold action is activated even if the hold timeout hasn’t expired yet

  • tap-hold-release

    • If there is a press+release of a different key, the hold action is activated even if the hold timeout hasn’t expired yet

These variants may be useful if you want more responsive tap-hold keys, but you should be wary of activating the hold action unintentionally.

Example:
(defalias
  anm (tap-hold         200 200 a @num) ;; tap: a      hold: numbers layer
  oar (tap-hold-press   200 200 o @arr) ;; tap: o      hold: arrows layer
  ech (tap-hold-release 200 200 e @chr) ;; tap: e      hold: chords layer
)

There are further additional variants of tap-hold-press and tap-hold-release:

  • tap-hold-press-timeout

  • tap-hold-release-timeout

These variants take a 5th parameter, in addition to the same 4 as the other variants. The 5th parameter is another action, which will activate if the hold timeout expires as opposed to being triggered by other key actions, whereas the non -timeout variants will activate the hold action in both cases.

  • tap-hold-release-keys

This variant takes a 5th parameter which is a list of keys that trigger an early tap when they are pressed while the tap-hold-release-keys action is waiting. Otherwise this behaves as tap-hold-release.

The keys in the 5th parameter correspond to the physical input keys, or in other words the key that corresponds to defsrc. This is in contrast to the fork and switch actions which operates on outputted keys, or in other words the outputs that are in deflayer, defalias, etc. for the corresponding defsrc key.

Example:
(defalias
  ;; tap: o    hold: arrows layer    timeout: backspace
  oat (tap-hold-press-timeout   200 200 o @arr bspc)
  ;; tap: e    hold: chords layer    timeout: esc
  ect (tap-hold-release-timeout 200 200 e @chr esc)
  ;; tap: u    hold: misc layer      early tap if any of: (a o e) are pressed
  umk (tap-hold-release-keys 200 200 u @msc (a o e))
)

  • tap-hold-except-keys

This variant takes a 5th parameter which is a list of keys that always trigger a tap when they are pressed while the tap-hold-except-keys action is waiting. No key is ever output until there is either a release of the key or any other key is pressed. This differs from tap-hold behaviour.

The keys in the 5th parameter correspond to the physical input keys, or in other words the key that corresponds to defsrc. This is in contrast to the fork and switch actions which operates on outputted keys, or in other words the outputs that are in deflayer, defalias, etc. for the corresponding defsrc key.

Example:
(defalias
  ;; tap: o    hold: arrows layer    timeout: backspace
  oat (tap-hold-press-timeout   200 200 o @arr bspc)
  ;; tap: e    hold: chords layer    timeout: esc
  ect (tap-hold-release-timeout 200 200 e @chr esc)
  ;; tap: u    hold: misc layer      always tap if any of: (a o e) are pressed
  umk (tap-hold-except-keys 200 200 u @msc (a o e))
)

macro

The macro action will tap a sequence of keys with optional delays. This is different from multi because in the multi action, all keys are held, whereas in macro, keys are pressed then released.

This means that with macro you can have some letters capitalized and others not. This is not possible with multi.

The macro action accepts one or more keys, some actions, chords, and delays (unit: ms). It also accepts a list prefixed with output chord modifiers where the list is subject to the aforementioned restrictions. The number keys will be parsed as delays, so they must be aliased to be used in a macro.

Up to 4 macros can be active at the same time.

The actions supported in macro are:

Note
 Some of these actions may need short delays between. For example, (macro a (unmod b) 5 (unmod c) d)) needs the delay of 5 to work correctly.
Example:
(defalias
  : S-;
  8 8
  0 0
  🙃 (unicode 🙃)

  ;; Type "http://localhost:8080"
  lch (macro h t t p @: / / 100 l o c a l h o s t @: @8 @0 @8 @0)

  ;; Type "I am HAPPY my FrIeNd 🙃"
  hpy (macro S-i spc a m spc S-(h a p p y) spc m y S-f r S-i e S-n d spc @🙃)

  ;; alt-tab(x3) and alt-shift-tab(x3) with macro
  tfd (macro A-(tab 200 tab 200 tab))
  tbk (macro A-S-(tab 200 tab 200 tab))
)

There is a variant of the macro action that will cancel all active macros upon releasing the key: macro-release-cancel. It is parsed identically to the non-cancelling version. An example use case for this action is holding down a key to get different outputs, similar to tap-dance but one can see which keys are being outputted.

E.g. in the example below, when holding the key, first 1 is typed, then replaced by ! after 500ms, and finally that is replaced by @ after another 500ms. However, if the key is released, the last character typed will remain and the rest of the macro does not run.

(defalias
  1 1

  ;; macro-release-cancel to output different characters with visual feedback
  ;; after holding for different amounts of time.
  1!@ (macro-release-cancel @1 500 bspc S-1 500 bspc S-2)
)

There are further variants of the two macro actions which repeat while held. The repeat will only occur once all macros have completed, including the held macro key. If multiple repeating macros are being held simulaneously, only the most recently pressed macro will be repeated.

(defalias
  mr1 (macro-repeat mltp)
  mr2 (macro-repeat-release-cancel mltp)
)

dynamic-macro

The dynamic-macro actions allow for recording and playing key presses. The dynamic macro records physical key presses, as opposed to kanata’s outputs. This allows the dynamic macro to replicate any action, but it means that if the macro starts and ends on different layers, then the macro might not be properly repeatable.

The action dynamic-macro-record accepts one number (0-65535), which represents the macro ID. Activating this action will begin recording physical key inputs. If dynamic-macro-record with the same ID is pressed again, the recording will end and be saved. If dynamic-macro-record with a different ID is pressed then the current recording will end and be saved, then a new recording with the new ID will begin.

The action dynamic-macro-record-stop will stop and save any active recording. There is a variant of this: dynamic-macro-record-stop-truncate This is a list action that takes a single parameter: the number of key actions to remove at the end of a dynamic macro. This variant is useful if the macro stop button is on a different layer.

The action dynamic-macro-play accepts one number (0-65535), which represents the macro ID. Activating this action will play the saved recording of physical keys from a previous dynamic-macro-record with the same macro ID, if it exists.

One can nest dynamic macros within each other, e.g. activate (dynamic-macro-play 1) while recording with (dynamic-macro-record 0). However, dynamic macros cannot recurse; e.g. activating (dynamic-macro-play 0) while recording with (dynamic-macro-record 0) will be ignored.

Example:
(defalias
  dr0 (dynamic-macro-record 0)
  dr1 (dynamic-macro-record 1)
  dr2 (dynamic-macro-record 2)
  dp0 (dynamic-macro-play 0)
  dp1 (dynamic-macro-play 1)
  dp2 (dynamic-macro-play 2)
  dms dynamic-macro-record-stop
  dst (dynamic-macro-record-stop-truncate 1)
)

fork

The fork action accepts two actions and a key list. The first (left) action will activate by default. The second (right) action will activate if any of the keys in the third parameter (right-trigger-keys) are currently active.

Example:
(defalias
  frk (fork k @special (lalt ralt))
)

caps-word

The caps-word action triggers a state where the lsft key will be added to the active key list when a set of specific keys are active. The keys are: a-z and -, which will be outputted as A-Z and _ respectively when using the US layout.

Examples where this is helpful is capitalizing a single important word like in IMPORTANT! or defining a constant in code like const P99_99_VALUE: …​. This has an advantage over the regular caps lock because it automatically ends so it doesn’t need to be toggled off manually, and it also shifts - to _ which caps lock does not do.

The caps-word state ends when the keyboard is idle for the duration of the defined timeout (1st parameter), or a terminating key is pressed. Every key is a terminating key except the keys which get capitalized and the extra keys in this list:

  • 0-9

  • kp0-kp9

  • bspc del

  • up down left rght

You can use caps-word-custom instead of caps-word if you want to manually define which keys are capitalized (2nd parameter) and what the extra non-terminal+non-capitalized keys should be (3rd parameter).

(defalias
  cw (caps-word 2000)

  ;; This example is similar to the default caps-word behaviour but it moves the
  ;; 0-9 keys to the capitalized key list from the extra non-terminating key list.
  cwc (caps-word-custom
    2000
    (a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
    (kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 bspc del up down left rght)
  )
)

unmod

The unmod action will release all modifiers temporarily and send one or more keys. After the unmod key is released, the released modifiers are pressed again. The modifiers affected are: lsft,rsft,lctl,rctl,lmet,rmet,lalt,ralt.

A variant of unmod is unshift. This action only releases the lsft,rsft keys. This can be useful for forcing unshifted keys while AltGr is still held.

Example:
(defalias
  ;; holding shift and tapping a @um1 key will still output 1.
  um1 (unmod 1)
  ;; dead keys é (as opposed to using AltGr) that outputs É when shifted
  dké (macro (unmod ') e)

  ;; In ISO German QWERTZ, force unshifted symbols even if shift is held
  { (unshift ralt 7)
  [ (unshift ralt 8)
)

cmd

The cmd action executes a program with arguments. It accepts one or more strings. The first string is the program that will be run and the following strings are arguments to that program. The arguments are provided to the program in the order written in the config file.

Note
 The command is executed directly and not via a shell, so you cannot make use of environment variables, e.g. ~ or $HOME in Linux will not be substituted with your home directory.
Example:
(defalias
  cm1 (cmd rm -fr /tmp/testing)

  ;; You can use bash -c and then a quoted string to execute arbitrary text in
  ;; bash. All text within double-quotes is treated as a single string.
  cm2 (cmd bash -c "echo hello world")
)

There is a variant of cmd: cmd-output-keys. This variant reads the output of the executed program and reads it as an S-expression, similarly to the macro action. However — unlike macro — only keys, chords, and chorded lists are supported. Delays and other actions are not supported.

(defalias
  ;; bash: type date-time as YYYY-MM-DD HH:MM
  pdb (cmd-output-keys bash -c "date +'%F %R' | sed 's/./& /g' | sed 's/:/S-;/g' | sed 's/\(.\{20\}\)\(.*\)/\(\1 spc \2\)/'")

  ;; powershell: type date-time as YYYY-MM-DD HH:MM
  pdp (cmd-output-keys powershell.exe "echo '(' (((Get-Date -Format 'yyyy-MM-dd HH:mm').toCharArray() -join ' ').insert(20, ' spc ') -replace ':','S-;') ')'")
)

arbitrary-code

The arbitrary-code action allows sending an arbitrary number to kanata’s output mechanism. The press is sent when pressed, and the release sent when released. This action can be useful for testing keys that are not yet named or mapped in kanata. Please contribute findings with names and mappings, either in a GitHub issue or as a pull request!

Warning
 This is not cross platform!
Warning
 When using the Interception driver, this action is still sent over SendInput. 
(defalias
  ab1 (arbitrary-code 700)
)

Global overrides

The defoverrides optional configuration item allows you to create global key overrides, irrespective of what actions are used to generate those keys. It accepts pairs of lists:

  1. the input key list that gets replaced

  2. the output key list to replace the input keys with

Both input and output lists accept 0 or more modifier keys (e.g. lctl, rsft) and exactly 1 non-modifier key (e.g. 1, bspc).

Only zero or one defoverrides is allowed in a configuration file.

Example:
;; Swap numbers and their symbols with respect to shift
(defoverrides
  (1) (lsft 1)
  (2) (lsft 2)
  ;; repeat for all remaining numbers

  (lsft 1) (1)
  (lsft 2) (2)
  ;; repeat for all remaining numbers
)

Include other files

The include optional configuration item allows you to include other files into the configuration. This configuration accepts a single string which is a file path. The file path can be an absolute path or a relative path. The path will be relative to the defined configuration file.

At the time of writing, includes can only be placed at the top level. The included files also cannot contain includes themselves.

Example:
;; This is in the file initially read by kanata, e.g. kanata.kbd
(include other-file.kbd)

;; This is in the other file
(defalias
  included-alias XX
  ;; ...
)

;; This is in the other file
(deflayer included-layer
  ;; ...
)

Advanced/weird features

Fake keys

You can define up to 767 fake keys. These keys are not directly mapped to any physical key presses and can only be activated via these actions:

  • (on-press-fakekey <fake key name> <key action>): Activate a fake key action when pressing the key mapped to this action.

  • (on-release-fakekey <fake key name> <key action>): Activate a fake key action when releasing the key mapped to this action.

  • (on-idle-fakekey <fake key name> <key action> <idle time>): Activate a fake key action when kanata has been idle for at least idle time milliseconds.

A fake key can be defined in a deffakekeys configuration entry. Configuring this entry is similar to defalias, but you cannot make use of aliases inside of deffakekeys to shorten an action. You can however refer to previously defined fake keys.

The aforementioned <key action> can be one of four values:

  • press: Press the fake key. It will not be released until another action triggers a release or tap.

  • release: Release the fake key. If it’s not already pressed, this does nothing.

  • tap: Press and release the fake key. If it’s already pressed, this only releases it.

  • toggle: Press the fake key if not already pressed, otherwise release it.

Expanding on the on-idle-fakekey action some more, the wording that "kanata" has been idle is important. Even if the keyboard is idle, kanata may not yet be idle. For example, if a long-running macro is playing, or kanata is waiting for the timeout of actions such as caps-word or tap-dance, kanata is not yet idle, and the tick count for the <idle time> parameter will not yet be counting even if you no longer have any keyboard keys pressed.

Example:
(deffakekeys
  ctl lctl
  sft lsft
  met lmet
  alt lalt

  ;; Press all modifiers
  pal (multi
        (on-press-fakekey ctl press)
        (on-press-fakekey sft press)
        (on-press-fakekey met press)
        (on-press-fakekey alt press)
      )

  ;; Release all modifiers
  ral (multi
        (on-press-fakekey ctl release)
        (on-press-fakekey sft release)
        (on-press-fakekey met release)
        (on-press-fakekey alt release)
      )
)

(defalias
  psf (on-press-fakekey sft press)
  rsf (on-press-fakekey sft release)

  pal (on-press-fakekey pal tap)
  ral (on-press-fakekey ral tap)

  isf (on-idle-fakekey sft tap 1000)
)

(deflayer use-fake-keys
  @psf @rsf @pal @ral a s d f @isf
)

For more context, you can read the issue that sparked the creation of fake keys.

Something notable about fake keys is that they don’t always interrupt the state of an active tap-dance-eager. If a macro action is assigned to a fake key, this won’t interrupt a tap dance. However, most other action types, notably a "normal" key action like rsft will still interrupt a tap dance.

Aside: broken delay action

The implementation of the following actions are broken in many use cases: on-press-fakekey-delay, on-release-fakekey-delay.

Because these actions exist and might otherwise be discovered anyway, it seems better to warn about it here in the documentation. You should use the macro action instead. The macro action can operate on fake keys.

Sequences

The sldr action makes kanata go into "sequence" mode. The action name is short for "sequence leader". This comes from Vim which has the concept of a configurable sequence leader key. When in sequence mode, keys are not typed (by default) but are saved until one of the following happens:

  • A key is typed that does not match any sequence

  • sequence-timeout milliseconds elapses since the most recent key press

Sequences are configured similarly to deffakekeys. The first parameter of a pair must be a defined fake key name. The second parameter is a list of keys that will activate a fake key tap when typed in the defined order. More precisely, the action triggered is:

(on-press-fakekey <fake key name> tap)

Example:
(defseq git-status (g s t))
(deffakekeys git-status (macro g i t spc s t a t u s))
(defalias rcl (tap-hold-release 200 200 sldr rctl))

(defseq
    dotcom (. S-3)
    dotorg (. S-4)
)
(deffakekeys
    dotcom (macro . c o m)
    dotorg (macro . o r g)
)

For more context, you can read the design and motivation of sequences. You may also be interested in the document describing chords is sequences to read about how chords in sequences behave.

Override the global timeout and input mode

An alternative to using sldr is the sequence action. The syntax is (sequence <timeout>). This enters sequence mode with a sequence timeout different from the globally configured one.

The sequence action can also be called with a second parameter. The second parameter is an override for sequence-input-mode:

(sequence <timeout> <input-mode>)
Example:
;; Enter sequence mode and input . with a timeout of 250
(defalias dot-sequence (macro (sequence 250) 10 .))

;; Enter sequence mode and input . with a timeout of 250 and using hidden-delay-type
(defalias dot-sequence (macro (sequence 250 hidden-delay-type) 10 .))

Input chords

Not to be confused with output chords, chord actions allow you to perform various actions based on which specific combination of input keys are pressed together. Such an unordered combination of keys is called a "chord". Each chord can perform a different action, allowing you to bind up to 2^n - 1 different actions to just n keys.

Input chords are configured similarly to defalias with two extra parameters at the beginning of each defchords group: the name of the group and a timeout value after which a chord triggers if it isn’t triggered by a key release or press of a non-chord key before the timeout expires.

(defsrc a b c)
(deflayer default
  @cha @chb @chc
)

(defalias
  cha (chord example a)
  chb (chord example b)
  chc (chord example c)
)

(defchords example 500
  (a      ) a
  (   b   ) b
  (a     c) C-v
  (a  b  c) @three
)

The first item of each pair specifies the keys that make up a given chord. The second item of each pair is the action to be executed when the given chord is pressed and may be any regular or advanced action, including aliases. It currently cannot however contain another chord action.

Note that unlike with defseq, these keys do not directly correspond to real keys and are merely arbitrary labels that make sense within the context of the chord. They are mapped to real keys in layers by configuring the key in the layer to map to a (chord name key) action where name is the name of the chords group (above example) and key is one of these arbitrary labels.

It is perfectly valid to nest these chord actions that enter "chording mode" within other actions like tap-dance and that will work as one would expect. However, this only applies to the first key used to enter "chording mode". Once "chording mode" is active, all other keys will be directly handled by "chording mode" with no regard for wrapper actions; e.g. if a key is pressed and it maps to a tap-hold with a chord as the hold action within, that chord key will immediately activate instead of the key needing to be held for the timeout period.

Release behaviour

For single key actions and output chords — like lctl or S-tab — and for layer-while-held, an input chord will release the action only when all keys that are part of the input chord have been released. In other words, if even one key is held for the input chord then the output action will be continued to be held, but only for the mentioned action categories.

An exception to the behaviour described above for the action categories that would normally apply is if a chord decomposition occurs. A chord decomposition occurs when you input a chord that does not correspond to any action. When this happens, kanata splits up the key presses to activate other actions from the components of the input chord. In this scenario, the behaviour described in the next paragraph will occur.

For chord decompositions and all other action categories, the release behaviour is more confusing: the output action will end when any key is released during the timeout, or if the timeout expires, the output action ends when the first key that was pressed in the chord gets released. This inconsistency is a limitation of the current implementation. In these scenarios it is recommended to hold down all keys if you want to keep holding and to release all keys if you want to do a release. This is because it will probably be difficult to know which key was pressed first.

If you want to bypass the behaviour of keys being held for chord outputs, you could change the chord output actions to be macros instead. Using a macro will guarantee a rapid press+release for the output keys.

defaliasenvcond

There is a variant of defalias: defaliasenvcond. This variant is parsed similarly, but there must be an extra list parameter that comes before all of the name-action pairs.

The list must contain two strings. In order, these strings are: an environment variable name, and the environment variable value. When the environment variable defined by the name has the corresponding value when starting kanata, the aliases within will be active. Otherwise, the aliases will be skipped.

A use case for defaliasenvcond is when one has multiple devices which vary in layout of keys, e.g. different special keys on the bottom row. Using environment variables, one can use the same kanata configuration across those multiple devices while changing key behaviours to keep consistent behaviour of specific key positions across the multiple devices, when the hardware keys at those physical key positions are not the same.

Example:
(defaliasenvcond (LAPTOP lp1)
  met @lp1met
)

(defaliasenvcond (LAPTOP lp2)
  met @lp2met
)
Set environment variables in the current terminal process:
# powershell
$env:VAR_NAME = "var_value"

# bash
VAR_NAME=var_value

switch

The switch action accepts multiple cases. One case is a triple of:

  • keys check

  • action: to activate if keys check succeeds

  • fallthrough|break: choose to continue vs. stop evaluating cases

The default use of keys check behaves similarly to fork.

For example, the keys check (a b c) will activate the corresponding action if any of a, b, or c are currently pressed.

The keys check also accepts the boolean operators and|or to allow more complex use cases.

The order of cases matters. For example, if two different cases match the currently pressed keys, the case listed earlier in the configuration will activate first. If the early case uses break, the second case will not activate. Otherwise if fallthrough is used, the second case will activate sequentially after the first case. This idea generalizes to more than two cases, but the two case example is hopefully simple and effective enough.

Example:
(defalias
  swt (switch
    ;; case 1
    ((and a b (or c d) (or e f))) @ac1 break
    ;; case 2
    (a b c) @ac2 fallthrough
    ;; case 3
    () @ac3 break
  )
)

Below is a description of how this example behaves.

Case 1

((and a b (or c d) (or e f))) a break

Translating case 1’s keys check to some other common languages might look like:

(a && b && (c || d) && (e || f))

If the keys check passes, the action @ac1 will activate. No other action will activate since break is used.

Cases 2 and 3

(a b c) c fallthrough
() b break

Case 2’s key check behaves like that of fork, i.e.

(or a b c)

or for some other common languages:

a || b || c

If this keys check passes and the case 1 does not pass, the action @ac2 will activate first. Since the keys check of case 3 always passes, @ac3 will activate next.

If neither case 1 or case 2 pass their keys checks, case 3 will always activate with @ac3.

key-history

In addition to simple keys, you can use the key-history list item within a case. This accepts, in order, a key and the key recency. The key recency must be in the range 1-8, where 1 is the most recent key that was pressed and 8 is 8th most recent key pressed.

Example:
(defalias
  swh (switch
    ((key-history a 1)) S-a break
    ((key-history b 1)) S-b break
    ((key-history c 1)) S-c break
    ((key-history d 8)) (macro d d d) break
    () XX break
  )
)

Custom tap-hold behaviour

This is not currently configurable without modifying the source code, but if you’re willing and/or capable, there is a tap-hold behaviour that is currently not exposed. Using this behaviour, one can be very particular about when and how tap vs. hold will activate by using extra information. The available information that can be used is exactly which keys have been pressed or released as well as the timing in milliseconds of those key presses. The action tap-hold-release-keys makes use of some of this capability, but doesn’t make full use of the power of this functionality.

For more context, you can read the motivation for custom tap-hold behaviour.