Configuration

Back to ToC

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:

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.

Back to ToC

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.

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

Back to ToC

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

An example minimal configuration is:

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

Ensure kanata and other key remapping programs are not running. Then you can use this link and press the key. The event.code field tells you the key name. Alternatively, you can read through this reference. Due to the lengthy key names, you may want to use deflayermap if remapping using these key names.

You can use deflocalkeys to define additional key names that can be used in defsrc, deflayer and anywhere else in the configuration.

There are five variants of deflocalkeys:

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!

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 in the code: <number> section. (prebuilt binary)

In Windows uning winIOv2, the winIOv2 executable variant will give the correct number in the code: <number> section.

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

However, Interception and winIOv2 should generally agree with each other.

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 🙂.

Back to ToC

The process-unmapped-keys option in defcfg is probably the most generally impactful option. Enabling this configuration makes kanata process keys that are not defined in defsrc. This might be 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 option 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 Windows only: windows-altgr.

Back to ToC

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

The defalias entry 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.

A list is a sequence of strings or nested lists 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.

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.

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.

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.

Back to ToC

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 are referred to by prefixing their name with $.

Back to ToC

You can put the lrld action onto a key to live reload your configuration file. If kanata can’t parse the file, the previous configuration will continue to be used. When live reload is activated, the active kanata layer will be the first deflayer defined in the configuration.

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.

Another variant is the list action lrld-num. This reloads the configuration file specified by the number, according to the order that the configuration file arguments are passed into kanata’s startup command.

Example specifying multiple config files in the command line:

Given the above startup command, activating (lrld-num 2) would reload the 2nd.cfg file.

Back to ToC

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.

Back to ToC

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.

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.

Back to ToC

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. (alternatively you can use ‗ ≝)

Back to ToC

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. (alternatively you can use ✗ ∅ •)

Back to ToC

The unicode (or 🔣) action accepts a single unicode character (but not a composed character, so 🤲, but not 🤲🏿). The character will not be repeatedly typed if you hold the key down.

You may use a unicode character as an alias if desired or in its simplified form 🔣😀 (vs the usual (🔣 😀)).

Back to ToC

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:

These modifiers may be combined together if desired.

Output chords are typically used do one-off actions such as:

Back to ToC

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.

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.

Back to ToC

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

NOTE: A lower-level detail of these actions is that they operate on output states as opposed to virtually releasing an input key. This does have some practical significance but for the most part it is not important.

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.

Back to ToC

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.

Back to ToC

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

Back to ToC

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:

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

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:

Back to ToC

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:

If a one-shot key is held then it will act as the regular key. E.g. holding a key assigned with @os2 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:

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.

Back to ToC

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:

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:

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

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

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.

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.

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.

Back to ToC

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:

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.

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.

Back to ToC

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.

Back to ToC

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.

Back to ToC

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:

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).

Back to ToC

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.

Back to ToC

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. Lists may also be used within cmd which you may desire to do for reuse via defvar. Lists will be flattened such that arguments are provided to the program in the order written in the config file, regardless of list nesting. To be technical, it would be a depth-first flattening (similar to DFS).

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.

Back to ToC

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!

Back to ToC

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.

Back to ToC

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

Back to ToC

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

The options are:

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.

Back to ToC

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

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

Back to ToC

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.

Back to ToC

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 https://github.com/jtroo/kanata/issues/435.

Back to ToC

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.

Back to ToC

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.

Back to ToC

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

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.

Back to ToC

If you desire to use only a subset of your keyboard you can use block-unmapped-keys to make every key other than those that exist in defsrc a no-op.

Back to ToC

This configuration applies to the following events:

These events are delayed the defined number of milliseconds (approximate). The default value is 5.

While the release is delayed, further processing of inputs is also paused. This means that there will be a minor input latency impact in the mentioned scenarios. Since 5ms is 1 frame for a 200 Hz refresh rate, in most scenarios this will not be perceptible.

The reason for this configuration existing is that some environments do not process the scenarios correctly due to the rapidity of the release. Kanata does send the events in the correct order, so the fault is more in the environment, but kanata provides a workaround anyway.

If you are negatively impacted by the latency increase of these events and your environment is not impacted by increased rapidity, you can set reduce the value to a number 0 to 4.

Back to ToC

This configuration affects the timer during which chords processing is disabled. NOTE: For more info, see Input chords / combos (v2).

The default (and minimum) value is 5 and the unit is milliseconds.

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.

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

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:

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.

Back to ToC

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:

Back to ToC

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.

Back to ToC

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

Back to ToC

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.

Back to ToC

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:

Back to ToC

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.

Back to ToC

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.

Back to ToC

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:

For more context, see: https://github.com/jtroo/kanata/issues/55.

Back to ToC

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 release binaries).

The original 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.

Hwids in Kanata are byte array representations of a concatenation of the ASCII hardware ids, which can be seen in Device Manager on Windows. As such, they are an arbitrary length and can be very long.

Relevant issue.

Back to ToC

This item has a similar purpose as the singular version documented above, but is instead a list of strings that allows multiple mice to be intercepted.

If both the singular and list items are used, the singular version will behave as if added to the list.

Back to ToC

This defcfg item allows you to intercept only specific keyboards. Its value must be a list of strings with each string representing one hardware ID.

To know what numbers to put into the string, you can run the variant with this defcfg item empty. Then when a button is first pressed on the keyboard, 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.

Hwids in Kanata are byte array representations of a concatenation of the ASCII hardware ids, which can be seen in Device Manager on Windows. As such, they are an arbitrary length and can be very long.

Back to ToC

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

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.

Back to ToC

You can define up to 767 virtual keys. These keys are not directly mapped to any physical key presses or releases. Virtual keys can be activated via special actions:

The <action> parameter can be one of:

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

Expanding on the on-idle 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.

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

Something notable about virtual 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.

Back to ToC

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:

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

(on-press tap-vkey <virtual key name>)

There are 10 special keys with names nop0-nop9 which kanata treats specially. Kanata will never send OS events for these keys but they can still participate in sequences.

See an example of using the nop keys alongside templates to define sequences below.

If 10 special nop keys do not seem sufficient, you can get creative with your sequences and treat some as a prefix modifier. For example, you can get 28 "keys" by treating nop0-nop6 as normal while treating nop7-nop9 as prefixes:

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

Back to ToC

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.

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. The behaviour also applies to the actions mentioned above when used inside of multi but not within any other action.

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.

Back to ToC

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.

Back to ToC

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

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|not 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.

Below is a description of how this example behaves.

Back to ToC

The top-level configuration item deftemplate declares a template that can be expanded multiple times via the list item template-expand.

The parameters to deftemplate in order are:

Within the template content, variable names prefixed with $ will be substituted with the expression passed into template-expand.

The list item template-expand can be placed as a top-level list or within another list. Its parameters in order are:

Example 1:

In a simple example, let’s say you wanted to set a large group of keys to do something different when you’re holding alt. Yes, this could also be handled with remapping alt to a layer shift, but there are cases where you wouldn’t want this. Rather than retyping the code with fork and unmod (to release alt) a bunch of times, you could template it like so:

Back to ToC

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.

Back to ToC

Instead of using the same a-z letters for special keys, e.g., lsft for LeftShift you can use much shorter, yet more visible, key symbols like ‹⇧.

For more details see symbol list and example config, which not only uses these symbols in layer definitions, but also repurposes ⎇› and ⇧› ⎇› keys into "symbol" keys that allow you to insert these fancy symbols by pressing the key, e.g.,

Back to ToC

The default kanata.exe binary doesn’t work in elevated windows (run with administrative privileges), e.g., Control Panel. However, you can use AutoHotkey’s "EnableUIAccess" script to self-sign the binary, move it to "Program Files", then launching kanata from there will also work in these elevated windows. See EnableUIAccess folder with the script and its requires libraries (needs AutoHotkey v1 installed)

If compiling yourself, you should add the feature flag win_manifest to enable the use of the EnableUIAccess script:

Back to ToC

Kanata has a kanata_simulated_input tool to help test your configuration in a predictable manner.

You can try it out on GitHub pages.

Code for the CLI tool can be found under simulated_input.

Instead of physically typing to test something and wondering whether you didn’t get the expected result because your config is wrong or because you mistyped something, you can write a sequence of key presses in a sim.txt file, run the tool with your config and get a "timeline" view of input/output events that can help understand how kanata translates your input into various key/mouse presses.

For more details download the files below and run kanata_simulated_input -c sim.kbd -s sim.txt
- example config with simple home row mod bindings
- example input sequence
- example output sequence

Input sequence file format: whitespace insensitive list of prefix:key pairs where prefix is one of:
- 🕐, t, or tick to add time between key events in ms
- ↓, d, down, or press
- ↑, u, up, or release
- ⟳, r, or repeat

And key names are defined in the str_to_oscode function, for example, 1 for the numeric key 1 or kp1/🔢₁ for the keypad numeric key 1

Using unicode symbols 🕐,↓,↑,⟳ allows skipping the : separator, e.g., ↓k ≝ ↓:k ≝ d:k