Keymap: description: | A keymap. kind: variable variants: - kind: string description: | Defines a keymap by its XKB representation. - Example: ```toml keymap = """ xkb_keymap { xkb_keycodes { include "evdev+aliases(qwerty)" }; xkb_types { include "complete" }; xkb_compat { include "complete" }; xkb_symbols { include "pc+us+inet(evdev)" }; }; """ ``` - kind: table description: | Defines or references a keymap. - Example: ```toml keymap.name = "my-keymap" [[keymaps]] name = "my-keymap" path = "./my-keymap.xkb" ``` fields: name: kind: string required: false description: | Defines a keymap name or references a defined keymap. If the value is set in the top-level `keymaps` array, it defines a named keymap. Otherwise it references a named keymap that should have been defined in the `keymaps` array. map: kind: string required: false description: | Defines a keymap by its XKB representation. For each keymap defined in the top-level `keymaps` array, exactly one of `map` and `path` has to be defined. path: kind: string required: false description: | Loads a keymap's XKB representation from a file. If the path is relative, it will be interpreted relative to the Jay config directory. For each keymap defined in the top-level `keymaps` array, exactly one of `map` and `path` has to be defined. Action: description: | An `Action` is an action performed by the compositor. - Example: ```toml [shortcuts] alt-q = "quit" ``` kind: variable variants: - kind: string ref: SimpleActionName description: | The value should be the name of a `simple` action. See the description of that variant for more details. - Example: ```toml [shortcuts] alt-q = "quit" ``` - kind: string pattern: "^\\$.*$" description: | The value should be the name of a `named` action, prefixed with the `$` character. This is the same as using the `named` action with the `$` removed. - Example: ```toml [actions] q = "quit" [shortcuts] alt-q = "$q" ``` - kind: array items: ref: Action description: | A list of actions to execute in sequence. - Example: ```toml [shortcuts] alt-q = [ { type = "exec", exec = ["notify-send", "exiting"] }, "quit", ] ``` - kind: table description: '' types: simple: description: | A simple action that takes no arguments. These are usually written as plain strings instead. - Example 1: ```toml [shortcuts] alt-q = { type = "simple", cmd = "quit" } ``` - Example 2: ```toml [shortcuts] alt-q = "quit" ``` fields: cmd: description: The simple action to execute. required: true ref: SimpleActionName named: description: | A named action that was defined via the top-level `actions` table or a `define-action` action. These are usually written as plain strings with a `$` prefix. - Example 1: ```toml [actions] my-action = "quit" [shortcuts] alt-q = { type = "named", name = "my-action" } ``` - Example 2: ```toml [shortcuts] alt-q = [ { type = "define-action", name = "my-action", action = "quit" }, { type = "named", name = "my-action" }, ] ``` fields: name: kind: string description: The named action to execute. required: true multi: description: | A list of actions to execute in sequence. These are usually written as plain arrays instead. - Example 1: ```toml [shortcuts] alt-q = { type = "multi", actions = ["quit", "quit"] } ``` - Example 2: ```toml [shortcuts] alt-q = ["quit", "quit"] ``` fields: actions: description: The actions to execute. required: true kind: array items: ref: Action exec: description: | Executes a program. - Example: ```toml [shortcuts] ctrl-a = { type = "exec", exec = "alacritty" } ctrl-b = { type = "exec", exec = ["notify-send", "hello world"] } ``` fields: exec: description: The command to execute. required: true ref: Exec switch-to-vt: description: | Switches to a virtual terminal. - Example: ```toml [shortcuts] ctrl-alt-F1 = { type = "switch-to-vt", num = 1 } ``` fields: num: description: | The VT number to switch to. required: true kind: number integer_only: true minimum: 1 show-workspace: description: | Switches to a workspace. - Example: ```toml [shortcuts] alt-F1 = { type = "show-workspace", name = "1" } ``` fields: name: description: The name of the workspace. required: true kind: string move-to-workspace: description: | Moves the currently focused window to a workspace. - Example: ```toml [shortcuts] alt-F1 = { type = "move-to-workspace", name = "1" } ``` fields: name: description: The name of the workspace. required: true kind: string move-to-output: description: | Moves a workspace to a different output. - Example 1: ```toml [shortcuts] alt-F1 = { type = "move-to-output", workspace = "1", output.name = "right" } ``` - Example 2: ```toml [shortcuts] alt-F1 = { type = "move-to-output", output.name = "right" } ``` fields: workspace: description: | The name of the workspace. If this is omitted, the currently active workspace is moved. required: false kind: string output: description: | The output to move to. If multiple outputs match, the workspace is moved to the first matching output. required: true ref: OutputMatch configure-connector: description: | Applies a configuration to connectors. - Example: ```toml [shortcuts] alt-j = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = false } } alt-k = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = true } } ``` fields: connector: description: The connector configuration. required: true ref: Connector configure-input: description: | Applies a configuration to input devices. - Example: ```toml [shortcuts] alt-l = { type = "configure-input", input = { match.tag = "mouse", left-handed = true } } alt-r = { type = "configure-input", input = { match.tag = "mouse", left-handed = false } } [[inputs]] tag = "mouse" match.is-pointer = true ``` fields: input: description: The input configuration. required: true ref: Input configure-idle: description: | Configures the idle timeout. - Example: ```toml [shortcuts] alt-l = { type = "configure-idle", idle.minutes = 0 } alt-r = { type = "configure-idle", idle.minutes = 10 } ``` fields: idle: description: The idle timeout. required: true ref: Idle configure-output: description: | Applies a configuration to input devices. - Example: ```toml [shortcuts] alt-l = { type = "configure-output", output = { match.name = "right", transform = "none" } } alt-r = { type = "configure-output", output = { match.name = "right", transform = "rotate-90" } } [[outputs]] name = "right" match.serial-number = "33K03894SL0" ``` fields: output: description: The output configuration. required: true ref: Output set-env: description: | Sets environment variables for all programs started afterwards. - Example: ```toml [shortcuts] alt-l = { type = "set-env", env.GTK_THEME = "Adwaita:dark" } ``` fields: env: description: The environment variables. required: true kind: map values: kind: string unset-env: description: | Unsets environment variables for all programs started afterwards. - Example: ```toml [shortcuts] alt-l = { type = "unset-env", env = ["Adwaita:dark"] } ``` fields: env: description: The environment variables. required: true kind: array items: kind: string set-keymap: description: | Sets the keymap. - Example: ```toml [shortcuts] alt-j = { type = "set-keymap", keymap.name = "laptop" } alt-k = { type = "set-keymap", keymap.name = "external" } [[keymaps]] name = "laptop" path = "./laptop-keymap.xkb" [[keymaps]] name = "external" path = "./external-keymap.xkb" ``` fields: keymap: description: The keymap. required: true ref: Keymap set-repeat-rate: description: | Sets the keyboard repeat rate. - Example: ```toml [shortcuts] alt-x = { type = "set-repeat-rate", rate = { rate = 25, delay = 250 } } ``` fields: rate: description: The rate. required: true ref: RepeatRate set-status: description: | Sets the status command. - Example: ```toml [shortcuts] alt-j = { type = "set-status", status = { exec = "i3status" } } ``` fields: status: description: | The status setting. Omitting this causes the status to be reset to empty. required: false ref: Status set-theme: description: | Sets the theme. - Example: ```toml [shortcuts] alt-j = { type = "set-theme", theme.bg-color = "#ff0000" } ``` fields: theme: description: The theme. required: true ref: Theme set-log-level: description: | Sets the log level of the compositor.. - Example: ```toml [shortcuts] alt-j = { type = "set-log-level", level = "debug" } ``` fields: theme: description: The log level. required: true ref: LogLevel set-gfx-api: description: | Sets the graphics API used by new DRM devices. Setting this after the compositor has started usually has no effect. - Example: ```toml [shortcuts] alt-j = { type = "set-gfx-api", api = "Vulan" } ``` fields: api: description: The API. required: true ref: GfxApi configure-direct-scanout: description: | Configure whether the compositor attempts direct scanout of client surfaces. - Example: ```toml [shortcuts] alt-j = { type = "configure-direct-scanout", enabled = false } ``` fields: enabled: description: Whether direct scanout is enabled. required: true kind: boolean configure-drm-device: description: | Applies a configuration to DRM devices. - Example: ```toml [shortcuts] alt-j = { type = "configure-drm-device", dev = { match.name = "integrated", gfx-api = "Vulkan" } } [[drm-devices]] name = "integrated" match.syspath = "/sys/devices/pci0000:00/0000:00:08.1/0000:14:00.0" ``` fields: dev: description: The DRM device configuration. required: true ref: DrmDevice set-render-device: description: | Sets the render device used for compositing. Changing this after the compositor has started might cause client windows to become invisible until they are resized. - Example: ```toml [shortcuts] alt-j = { type = "set-render-device", dev.name = "integrated" } [[drm-devices]] name = "integrated" match.syspath = "/sys/devices/pci0000:00/0000:00:08.1/0000:14:00.0" ``` fields: dev: description: | The rule to find the device. The first matching device is used. required: true ref: DrmDeviceMatch define-action: description: | Defines a name for an action. Usually you would define these by using the top-level `actions` table. This action can be used to re-define actions. - Example: ```toml [actions] a1 = "quit" a2 = "$a1" [shortcuts] alt-q = [ { type = "define-action", name = "a2", action = [] }, "$2", # does nothing ] ``` fields: name: kind: string description: The name of the action. required: true action: description: The action to execute. required: true ref: Action undefine-action: description: | Removes a named action. fields: name: kind: string description: The name of the action. required: true create-mark: description: | Creates a mark for the currently focused window. - Example 1: This example interactively selects a key that identifies the mark. ```toml [shortcuts] alt-x = { type = "create-mark" } ``` - Example 2: This example hard-codes a key. ```toml [shortcuts] alt-x = { type = "create-mark", id.key = "a" } ``` fields: id: description: | The identifier of the mark. If this field is omitted, the next pressed key identifies the mark. required: false ref: MarkId jump-to-mark: description: | Moves the keyboard focus to a window identified by a mark. - Example 1: This example interactively selects a key that identifies the mark. ```toml [shortcuts] alt-x = { type = "jump-to-mark" } ``` - Example 2: This example hard-codes a key. ```toml [shortcuts] alt-x = { type = "jump-to-mark", id.key = "a" } ``` fields: id: description: | The identifier of the mark. If this field is omitted, the next pressed key identifies the mark. required: false ref: MarkId copy-mark: description: | Copies a mark. If the `src` id identifies a mark before this function is called, the `dst` id will identify the same mark afterwards. fields: src: description: The source id to copy from. required: true ref: MarkId dst: description: The destination id to copy to. required: true ref: MarkId push-mode: description: | Pushes an input mode on top of the input-mode stack. The mode can be popped with the `pop-mode` action. - Example: ```toml [shortcuts] alt-x = { type = "push-mode", name = "navigation" } ``` fields: name: description: The name of the mode. required: true kind: string latch-mode: description: | Temporarily pushes an input mode on top of the input-mode stack. The new mode will automatically be popped when the next shortcut is invoked. - Example: ```toml [shortcuts] alt-x = { type = "latch-mode", name = "navigation" } ``` fields: name: description: The name of the mode. required: true kind: string Exec: description: | Describes how to execute a program. - Example 1: ```toml [shortcuts] ctrl-a = { type = "exec", exec = "alacritty" } ``` - Example 2: ```toml [shortcuts] ctrl-a = { type = "exec", exec = ["notify-send", "hello world"] } ``` - Example 3: ```toml [shortcuts] ctrl-a = { type = "exec", exec = { prog = "notify-send", args = ["hello world"], env.WAYLAND_DISPLAY = "2" } } ``` kind: variable variants: - kind: string description: | The name of the executable to execute. - Example: ```toml [shortcuts] ctrl-a = { type = "exec", exec = "alacritty" } ``` - kind: array items: kind: string description: | The name and arguments of the executable to execute. - Example: ```toml [shortcuts] ctrl-a = { type = "exec", exec = ["notify-send", "hello world"] } ``` - kind: table description: | The name, arguments, and environment variables of the executable to execute. - Example: ```toml [shortcuts] ctrl-a = { type = "exec", exec = { prog = "notify-send", args = ["hello world"], env.WAYLAND_DISPLAY = "2" } } ``` fields: prog: kind: string required: true description: The name of the executable. args: kind: array required: false items: kind: string description: The arguments to pass to the executable. env: kind: map required: false values: kind: string description: The environment variables to pass to the executable. privileged: kind: boolean required: false description: | If `true`, the executable gets access to privileged wayland protocols. The default is `false`. SimpleActionName: description: | The name of a `simple` Action. When used inside a window rule, the following actions apply to the matched window instead fo the focused window: - `move-left` - `move-down` - `move-up` - `move-right` - `split-horizontal` - `split-vertical` - `toggle-split` - `tile-horizontal` - `tile-vertical` - `toggle-split` - `show-single` - `show-all` - `toggle-fullscreen` - `enter-fullscreen` - `exit-fullscreen` - `close` - `toggle-floating` - `float` - `tile` - `toggle-float-pinned` - `pin-float` - `unpin-float` - Example: ```toml [shortcuts] alt-q = "quit" ``` kind: string values: - value: focus-left description: Move the keyboard focus to the left of the currently focused window. - value: focus-down description: Move the keyboard focus down from the currently focused window. - value: focus-up description: Move the keyboard focus up from the currently focused window. - value: focus-right description: Move the keyboard focus to the right of the currently focused window. - value: move-left description: Move the currently focused window one to the left. - value: move-down description: Move the currently focused window one down. - value: move-up description: Move the currently focused window one up. - value: move-right description: Move the currently focused window one to the right. - value: move-right description: Move the currently focused window one to the right. - value: split-horizontal description: Split the currently focused window horizontally. - value: split-vertical description: Split the currently focused window vertically. - value: toggle-split description: | Toggle the split of the currently focused container between vertical and horizontal. - value: tile-horizontal description: Sets the split of the currently focused container to horizontal. - value: tile-vertical description: Sets the split of the currently focused container to vertical. - value: toggle-mono description: | Toggle the currently focused container between showing a single and all children. - value: show-single description: Makes the currently focused container show a single child. - value: show-all description: Makes the currently focused container show all children. - value: toggle-fullscreen description: Toggle the currently focused window between fullscreen and windowed. - value: enter-fullscreen description: Makes the currently focused window fullscreen. - value: exit-fullscreen description: Makes the currently focused window windowed. - value: focus-parent description: Focus the parent of the currently focused window. - value: close description: Close the currently focused window. - value: disable-pointer-constraint description: | Disable the currently active pointer constraint, allowing you to move the pointer outside the window. The constraint will be re-enabled when the pointer re-enters the window. - value: toggle-floating description: Toggle the currently focused window between floating and tiled. - value: float description: Makes the currently focused window floating. - value: tile description: Makes the currently focused window tiled. - value: quit description: Terminate the compositor. - value: reload-config-toml description: Reload the `config.toml`. - value: reload-config-so description: Reload the `config.so`. - value: consume description: | Consume the current key event. Don't forward it to the focused application. This action only has an effect in shortcuts. Key-press events events that trigger shortcuts are consumed by default. Key-release events events that trigger shortcuts are forwarded by default. Note that consuming key-release events can cause keys to get stuck in the focused application. See the `forward` action to achieve the opposite effect. - value: forward description: | Forward the current key event to the focused application. See the `consume` action for more details. - value: none description: | Perform no action. As a special case, if this is the action of a shortcut, the shortcut will be unbound. This can be used in modes to unbind a key. - value: enable-window-management description: | Enables window management mode. In window management mode, floating windows can be moved by pressing the left mouse button and all windows can be resize by pressing the right mouse button. - value: disable-window-management description: | Disables window management mode. - value: enable-float-above-fullscreen description: | Enables floating windows showing above fullscreen windows. By default, floating windows are hidden below fullscreen windows. - value: disable-float-above-fullscreen description: | Disables floating windows showing above fullscreen windows. - value: toggle-float-above-fullscreen description: | Toggles floating windows showing above fullscreen windows. - value: pin-float description: | Pins the currently focused floating window. If a floating window is pinned, it will stay visible even when switching to a different workspace. - value: unpin-float description: | Unpins the currently focused floating window. - value: toggle-float-pinned description: | Toggles whether the currently focused floating window is pinned. - value: kill-client description: | Kills a client. Within a window rule, it applies to the client of the window. Within a client rule it applies to the matched client. Has no effect otherwise. - value: show-bar description: Shows the built-in bar. - value: hide-bar description: Hides the built-in bar. - value: toggle-bar description: Toggles the built-in bar. - value: focus-prev description: Focuses the previous window in the focus history. - value: focus-next description: Focuses the next window in the focus history. - value: focus-below description: Focuses the layer below the currently focused layer. - value: focus-above description: Focuses the layer above the currently focused layer. - value: focus-tiles description: Focuses the tile layer. - value: create-mark description: | Interactively creates a mark. The next pressed key becomes the identifier for the mark. - value: jump-to-mark description: | Interactively jumps to a mark. The next pressed key identifies the mark to jump to. - value: clear-modes description: Disables all previously set input modes, clearing the input-mode stack. - value: pop-mode description: Pops the topmost mode from the input-mode stack. Color: kind: string description: | A color. The format should be one of the following: - `#rgb` - `#rrggbb` - `#rgba` - `#rrggbba` ConnectorMatch: kind: variable description: | Rules to match one of the connectors used by the compositor. variants: - kind: array items: ref: ConnectorMatch description: | This rule matches if any of the rules in the array match. - kind: table description: | Describes a rule that matches a subset of connectors. This rule matches if all of the specified fields match. - Example: ```toml [[connectors]] match.name = "DP-1" ``` fields: name: kind: string required: false description: | The name of the connector. These values are not necessarily stable. You can find out the value by running `jay randr`. Connector: kind: table description: | Describes configuration to apply to a connector. - Example: To disable the built-in display of a laptop: ```toml [[connectors]] match.name = "eDP-1" enabled = false ``` fields: match: ref: ConnectorMatch required: true description: | The rule by which the connectors to modify are selected. enabled: kind: boolean required: false description: | If specified, enables or disables the connector. DrmDeviceMatch: kind: variable description: | Rules to match one of the DRM devices (graphics cards) used by the compositor. variants: - kind: array items: ref: DrmDeviceMatch description: | This rule matches if any of the rules in the array match. - kind: table description: | Describes a rule that matches a subset of DRM devices. This rule matches if all of the specified fields match. - Example: ```toml [[drm-devices]] name = "dedicated" match = { pci-vendor = 0x1002, pci-model = 0x73ff } ``` fields: name: kind: string required: false description: | The name of another DrmDeviceMatch rule. For this rule to match, the referenced rule must match. The name of the rule should have been defined in the top-level `drm-devices` array. This can be used to easily refer to DRM devices. - Example: ```toml [shortcuts] alt-v = { type = "configure-drm-device", dev = { match.name = "dedicated", gfx-api = "Vulkan" } } alt-o = { type = "configure-drm-device", dev = { match.name = "dedicated", gfx-api = "OpenGl" } } [[drm-devices]] name = "dedicated" match = { pci-vendor = 0x1002, pci-model = 0x73ff } ``` syspath: kind: string required: false description: | The syspath of the device. This is useful if you have multiple copies of the same device installed so that the PCI numbers are not unique. The values are usually stable unless you re-configure your hardware. - Example: ```toml [[drm-devices]] name = "integrated" match.syspath = "/sys/devices/pci0000:00/0000:00:08.1/0000:14:00.0" ``` devnode: kind: string required: false description: | The devnode of the device. The values are usually not-stable across PC restarts. - Example: ```toml [[drm-devices]] name = "integrated" match.devnode = "/dev/dri/card0" ``` vendor: kind: string required: false description: | The name of the vendor. - Example: ```toml [[drm-devices]] name = "integrated" match.vendor = "Advanced Micro Devices, Inc. [AMD/ATI]" ``` model: kind: string required: false description: | The name of the model. - Example: ```toml [[drm-devices]] name = "integrated" match.vendor = "Raphael" ``` pci-vendor: kind: number integer_only: true required: false description: | The PCI number of the vendor. - Example: ```toml [[drm-devices]] name = "integrated" match.pci-vendor = 0x1002 ``` pci-model: kind: number integer_only: true required: false description: | The PCI number of the model. - Example: ```toml [[drm-devices]] name = "integrated" match.pci-model = 0x164e ``` DrmDevice: kind: table description: | Describes configuration to apply to a DRM device (graphics card). - Example: To disable direct scanout on a device: ```toml [[drm-devices]] match = { pci-vendor = 0x1002, pci-model = 0x73ff } direct-scanout = false ``` fields: name: kind: string required: false description: | Assigns a name to the rule in the `match` field. This only has an effect when used in the top-level `drm-devices` array. match: ref: DrmDeviceMatch required: true description: | The rule by which the DRM devices to modify are selected. direct-scanout: kind: boolean required: false description: | If specified, enables or disables direct scanout on this device. gfx-api: ref: GfxApi required: false description: | If specified, sets the graphics API to use for this device. flip-margin-ms: kind: number required: false description: | If specified, sets the flip margin of this device. This is duration between the compositor initiating a page flip and the output's vblank event. This determines the minimum input latency. The default is 1.5 ms. Note that if the margin is too small, the compositor will dynamically increase it. GfxApi: kind: string description: A graphics API used for rendering. values: - value: OpenGl description: The OpenGL API. - value: Vulkan description: | The Vulkan API. Note that this API has the following restriction: If any of the DRM devices in the system use Vulkan, then all devices must support DRM format modifiers. This is usually the case but not for AMD devices older than RX 5xxx. InputMatch: kind: variable description: | Rules to match one of the input devices used by the compositor. variants: - kind: array items: ref: InputMatch description: | This rule matches if any of the rules in the array match. - kind: table description: | Describes a rule that matches a subset of input devices. This rule matches if all of the specified fields match. - Example: ```toml [[inputs]] match.is-pointer = true left-handed = true ``` fields: tag: kind: string required: false description: | The tag of another InputMatch rule. For this rule to match, the referenced rule must match. The name of the rule should have been defined in the top-level `inputs` array. This can be used to easily refer to input devices. - Example: ```toml [shortcuts] alt-l = { type = "configure-input", input = { match.tag = "mouse", left-handed = true } } alt-r = { type = "configure-input", input = { match.tag = "mouse", left-handed = false } } [[inputs]] tag = "mouse" match.is-pointer = true ``` name: kind: string required: false description: | The libinput name of the device. You can find out the name of the devices by running `jay input`. - Example: ```toml [[inputs]] match.name = "Logitech G300s Optical Gaming Mouse" left-handed = true ``` syspath: kind: string required: false description: | The syspath of the device. This is useful if you have multiple copies of the same device installed so that the name is not unique. The values are usually stable unless you re-configure your hardware. - Example: ```toml [[inputs]] match.syspath = "/sys/devices/pci0000:00/0000:00:08.1/0000:14:00.4/usb5/5-1/5-1.1/5-1.1.2/5-1.1.2:1.0" left-handed = true ``` devnode: kind: string required: false description: | The devnode of the device. The values are usually not-stable across PC restarts. - Example: ```toml [[inputs]] match.devnode = "/dev/input/event4" left-handed = true ``` is-keyboard: kind: boolean required: false description: | Whether the devices has been identified as a keyboard. - Example: ```toml [[inputs]] match.is-keyboard = false left-handed = true ``` is-pointer: kind: boolean required: false description: | Whether the devices has been identified as a pointer. - Example: ```toml [[inputs]] match.is-pointer = false left-handed = true ``` is-touch: kind: boolean required: false description: | Whether the devices has been identified as a touch device. - Example: ```toml [[inputs]] match.is-touch = true tap-enabled = true ``` is-tablet-tool: kind: boolean required: false description: | Whether the devices has been identified as a tablet tool. - Example: ```toml [[inputs]] match.is-tablet-tool = true tap-enabled = true ``` is-tablet-pad: kind: boolean required: false description: | Whether the devices has been identified as a tablet pad. - Example: ```toml [[inputs]] match.is-tablet-tool = true tap-enabled = true ``` is-gesture: kind: boolean required: false description: | Whether the devices has been identified as a switch. - Example: ```toml [[inputs]] match.is-switch = true ``` Input: kind: table description: | Describes configuration to apply to an input device. - Example: To make mice left handed: ```toml [[inputs]] match.is-pointer = true left-handed = true ``` fields: tag: kind: string required: false description: | Assigns a name to the rule in the `match` field. This only has an effect when used in the top-level `inputs` array. match: ref: InputMatch required: true description: | The rule by which the input devices to modify are selected. accel-profile: ref: AccelProfile required: false description: | The acceleration profile to use. See the libinput documentation for more details. accel-speed: kind: number required: false description: | The acceleration speed to use. Values should be in the range -1 to 1. See the libinput documentation for more details. tap-enabled: kind: boolean required: false description: | Whether tap is enabled for this device. See the libinput documentation for more details. tap-drag-enabled: kind: boolean required: false description: | Whether tap drag is enabled for this device. See the libinput documentation for more details. tap-drag-lock-enabled: kind: boolean required: false description: | Whether tap drag lock is enabled for this device. See the libinput documentation for more details. left-handed: kind: boolean required: false description: | Whether the device is left handed. See the libinput documentation for more details. natural-scrolling: kind: boolean required: false description: | Whether the device uses natural scrolling. See the libinput documentation for more details. middle-button-emulation: kind: boolean required: false description: | Converts a simultaneous left and right button click into a middle button click. See the libinput documentation for more details. click-method: ref: ClickMethod required: false description: | Defines how button events are triggered on a clickable touchpad. See the libinput documentation for more details. px-per-wheel-scroll: kind: boolean required: false description: | The number of pixels to scroll for each scroll wheel dedent. transform-matrix: kind: array items: kind: array items: kind: number required: false description: | A transformation matrix to apply to each motion event of this device. The matrix should be 2x2. - Example: To slow down the mouse to 35% of normal speed: ```toml [[inputs]] match.is-pointer = true transform-matrix = [[0.35, 0], [0, 0.35]] ``` keymap: ref: Keymap required: false description: | The keymap to use for this device. This overrides the global keymap. The keymap becomes active when a key is pressed. - Example: ```toml [[inputs]] match.name = "ZSA Technology Labs Inc ErgoDox EZ" keymap.name = "external" ``` on-lid-closed: ref: Action required: false description: | An action to execute when the laptop lid is closed. This should only be used in the top-level inputs array. - Example: ```toml [[inputs]] match.name = "" on-lid-closed = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = false } } on-lid-opened = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = true } } ``` on-lid-opened: ref: Action required: false description: | An action to execute when the laptop lid is opened. This should only be used in the top-level inputs array. - Example: ```toml [[inputs]] match.name = "" on-lid-closed = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = false } } on-lid-opened = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = true } } ``` on-converted-to-laptop: ref: Action required: false description: | An action to execute when the convertible device is converted to a laptop. This should only be used in the top-level inputs array. on-converted-to-tablet: ref: Action required: false description: | An action to execute when the convertible device is converted to a tablet. This should only be used in the top-level inputs array. output: ref: OutputMatch required: false description: | Maps this input device to an output. This is used to map touch screen and graphics tablets to outputs. - Example: ```toml [[inputs]] match.name = "Wacom Bamboo Comic 2FG Pen" output.connector = "DP-1" ``` remove-mapping: kind: boolean required: false description: | Removes the mapping of from this device to an output. This should only be used within `configure-input` actions. - Example: ```toml [shortcuts] alt-x = { type = "configure-input", input = { match.tag = "wacom", remove-mapping = true } } [[inputs]] tag = "wacom" match.name = "Wacom Bamboo Comic 2FG Pen" output.connector = "DP-1" ``` calibration-matrix: kind: array items: kind: array items: kind: number required: false description: | The calibration matrix of the device. This matrix should be 2x3. See the libinput documentation for more details. - Example: To flip the device 90 degrees: ```toml [[inputs]] calibration-matrix = [[0, 1, 0], [-1, 0, 1]] ``` AccelProfile: kind: string values: - value: Flat description: The flat profile. - value: Adaptive description: The adaptive profile. description: | The acceleration profile to apply to an input device. See the libinput documentation for more details. ClickMethod: kind: string values: - value: none description: No click method handling. - value: button-areas description: Bottom area of the touchpad is divided into a left, middle and right button area. - value: clickfinger description: | Number of fingers on the touchpad decide the button type. Clicking with 1, 2, 3 fingers triggers a left, right, or middle click, respectively. description: | The click method to apply to an input device. See the libinput documentation for more details. LogLevel: kind: string description: A log level. values: - value: trace description: Trace log level. - value: debug description: Debug log level. - value: info description: Info log level. - value: warn description: Warn log level. - value: error description: Error log level. Mode: kind: table description: | The mode of a display. - Example: ```toml [[outputs]] match.serial-number = "33K03894SL0" mode = { width = 1920, height = 1080, refresh-rate = 59.94 } ``` fields: width: kind: number integer_only: true required: true description: The width of the mode. height: kind: number integer_only: true required: true description: The height of the mode. refresh-rate: kind: number required: false description: The refresh rate of the mode in HZ. OutputMatch: kind: variable description: | Rules to match one of the outputs used by the compositor. variants: - kind: array items: ref: OutputMatch description: | This rule matches if any of the rules in the array match. - kind: table description: | Describes a rule that matches a subset of outputs. This rule matches if all of the specified fields match. - Example: ```toml [[outputs]] name = "right" match.serial-number = "33K03894SL0" x = 1920 y = 0 ``` fields: name: kind: string required: false description: | The name of another OutputMatch rule. For this rule to match, the referenced rule must match. The name of the rule should have been defined in the top-level `outputs` array. This can be used to easily refer to outputs. - Example: ```toml [shortcuts] alt-l = { type = "configure-output", output = { match.name = "right", transform = "none" } } alt-r = { type = "configure-output", output = { match.name = "right", transform = "rotate-90" } } [[outputs]] name = "right" match.serial-number = "33K03894SL0" ``` connector: kind: string required: false description: | The name of the connector the output is connected to. You can find out the name of the connector by running `jay randr`. - Example: ```toml [[outputs]] match.connector = "DP-1" scale = 1.25 ``` serial-number: kind: string required: false description: | The serial number of the output. You can find out the serial number by running `jay randr`. - Example: ```toml [[outputs]] match.serial-number = "33K03894SL0" scale = 1.25 ``` manufacturer: kind: string required: false description: | The manufacturer of the output. You can find out the manufacturer by running `jay randr`. - Example: ```toml [[outputs]] match.manufacturer = "BNQ" scale = 1.25 ``` model: kind: string required: false description: | The model of the output. You can find out the model by running `jay randr`. - Example: ```toml [[outputs]] match.model = "BenQ GW2480" scale = 1.25 ``` Output: kind: table description: | Describes configuration to apply to an output. - Example: To set the scale of an output. ```toml [[outputs]] match.serial-number = "33K03894SL0" scale = 1.25 ``` fields: name: kind: string required: false description: | Assigns a name to the rule in the `match` field. This only has an effect when used in the top-level `outputs` array. match: ref: OutputMatch required: true description: | The rule by which the outputs to modify are selected. x: kind: number integer_only: true minimum: 0 required: false description: | The x coordinate of the output in compositor space. y: kind: number integer_only: true minimum: 0 required: false description: | The y coordinate of the output in compositor space. scale: kind: number minimum: 0 exclusive_minimum: true required: false description: | The scale of the output. transform: ref: Transform required: false description: | The transform of the output. mode: ref: Mode required: false description: | The mode of the output. If the refresh rate is not specified, the first mode with the specified width and height is used. vrr: ref: Vrr required: false description: | Configures the VRR settings of this output. By default, the VRR mode is `never` and the cursor refresh rate is unbounded. - Example: ```toml [[outputs]] match.serial-number = "33K03894SL0" vrr = { mode = "always", cursor-hz = 90 } ``` tearing: ref: Tearing required: false description: | Configures the tearing settings of this output. By default, the tearing mode is `variant3`. - Example: ```toml [[outputs]] match.serial-number = "33K03894SL0" tearing.mode = "never" ``` format: ref: Format required: false description: | Configures the framebuffer format of this output. By default, the format is `xrgb8888`. - Example: ```toml [[outputs]] match.serial-number = "33K03894SL0" format = "rgb565" ``` color-space: ref: ColorSpace required: false description: | The color space of the output. transfer-function: ref: TransferFunction required: false description: | The transfer function of the output. brightness: ref: Brightness required: false description: | The brightness of the output. This setting has no effect unless the vulkan renderer is used. Transform: kind: string description: An output transformation. values: - value: none description: No transformation. - value: rotate-90 description: The content of the output is rotated 90 degrees counter clockwise. - value: rotate-180 description: The content of the output is rotated 180 degrees counter clockwise. - value: rotate-270 description: The content of the output is rotated 270 degrees counter clockwise. - value: flip description: The content of the output is flipped around the vertical axis. - value: flip-rotate-90 description: | The content of the output is flipped around the vertical axis and then rotated 90 degrees counter clockwise. - value: flip-rotate-180 description: | The content of the output is flipped around the vertical axis and then rotated 180 degrees counter clockwise. - value: flip-rotate-270 description: | The content of the output is flipped around the vertical axis and then rotated 270 degrees counter clockwise. MessageFormat: kind: string description: A message format used by status programs. values: - value: plain description: The messages are in plain text. - value: pango description: The messages contain pango markup. - value: i3bar description: The messages are in i3bar format. Status: kind: table description: | The configuration of a status program whose output will be shown in the bar. - Example: ```toml [status] format = "i3bar" exec = "i3status" ``` fields: format: ref: MessageFormat required: false description: The format used by the program. exec: ref: Exec required: true description: The program that will emit the status messages. i3bar-separator: kind: string required: false description: | The separator to be used between i3bar components. The default is ` | `. Theme: kind: table description: | The theme of the compositor. fields: attention-requested-bg-color: ref: Color required: false description: The background color of title that have requested attention. bg-color: ref: Color required: false description: The background color of the desktop. bar-bg-color: ref: Color required: false description: The background color of the bar. bar-status-text-color: ref: Color required: false description: The color of the status text in the bar. border-color: ref: Color required: false description: The color of the borders between windows. captured-focused-title-bg-color: ref: Color required: false description: The background color of focused titles that are being recorded. captured-unfocused-title-bg-color: ref: Color required: false description: The background color of unfocused titles that are being recorded. focused-inactive-title-bg-color: ref: Color required: false description: The background color of focused titles that are inactive. focused-inactive-title-text-color: ref: Color required: false description: The text color of focused titles that are inactive. focused-title-bg-color: ref: Color required: false description: The background color of focused titles. focused-title-text-color: ref: Color required: false description: The text color of focused titles. separator-color: ref: Color required: false description: The color of the separator between titles and window content. unfocused-title-bg-color: ref: Color required: false description: The background color of unfocused titles. unfocused-title-text-color: ref: Color required: false description: The text color of unfocused titles. highlight-color: ref: Color required: false description: Color used to highlight parts of the UI. border-width: kind: number integer_only: true minimum: 0 required: false description: The width of borders between windows. title-height: kind: number integer_only: true minimum: 0 required: false description: The height of tabs. font: kind: string required: false description: The name of the font to use. Config: kind: table description: | This is the top-level table. - Example: ```toml keymap = """ xkb_keymap { xkb_keycodes { include "evdev+aliases(qwerty)" }; xkb_types { include "complete" }; xkb_compat { include "complete" }; xkb_symbols { include "pc+us+inet(evdev)" }; }; """ on-graphics-initialized = { type = "exec", exec = "mako" } [shortcuts] alt-h = "focus-left" alt-j = "focus-down" alt-k = "focus-up" alt-l = "focus-right" alt-shift-h = "move-left" alt-shift-j = "move-down" alt-shift-k = "move-up" alt-shift-l = "move-right" alt-d = "split-horizontal" alt-v = "split-vertical" alt-t = "toggle-split" alt-m = "toggle-mono" alt-u = "toggle-fullscreen" alt-f = "focus-parent" alt-shift-c = "close" alt-shift-f = "toggle-floating" Super_L = { type = "exec", exec = "alacritty" } alt-p = { type = "exec", exec = "bemenu-run" } alt-q = "quit" alt-shift-r = "reload-config-toml" ctrl-alt-F1 = { type = "switch-to-vt", num = 1 } ctrl-alt-F2 = { type = "switch-to-vt", num = 2 } # ... alt-F1 = { type = "show-workspace", name = "1" } alt-F2 = { type = "show-workspace", name = "2" } # ... alt-shift-F1 = { type = "move-to-workspace", name = "1" } alt-shift-F2 = { type = "move-to-workspace", name = "2" } # ... ``` fields: keymap: ref: Keymap required: false description: | The keymap to use. - Example: ```toml keymap = """ xkb_keymap { xkb_keycodes { include "evdev+aliases(qwerty)" }; xkb_types { include "complete" }; xkb_compat { include "complete" }; xkb_symbols { include "pc+us+inet(evdev)" }; }; """ ``` repeat-rate: ref: RepeatRate required: false description: | The keyboard repeat rate. - Example: ```toml repeat-rate = { rate = 25, delay = 250 } ``` shortcuts: kind: map values: ref: Action required: false description: | The compositor shortcuts. The keys should be in the following format: ``` (MOD-)*KEYSYM ``` `MOD` should be one of `shift`, `lock`, `ctrl`, `mod1`, `mod2`, `mod3`, `mod4`, `mod5`, `caps`, `alt`, `num`, `logo`, or `release`. Using the `release` modifier causes the shortcut to trigger when the key is released. `KEYSYM` should be the name of a keysym. The authorative location for these names is [1] with the `XKB_KEY_` prefix removed. The keysym should be the unmodified keysym. E.g. `shift-q` not `shift-Q`. [1]: https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h - Example: ```toml [shortcuts] alt-q = "quit" ``` complex-shortcuts: kind: map values: ref: ComplexShortcut required: false description: | Complex compositor shortcuts. The keys should have the same format as in the `shortcuts` table. - Example: ```toml [complex-shortcuts.XF86AudioRaiseVolume] mod-mask = "alt" action = { type = "exec", exec = ["pactl", "set-sink-volume", "0", "+10%"] } ``` on-graphics-initialized: ref: Action required: false description: | An action to execute when the graphics have been initialized for the first time. This is a good place to start graphical applications. - Example: ```toml on-graphics-initialized = { type = "exec", exec = "mako" } ``` status: ref: Status required: false description: | The status program that will be used for the status text. - Example: ```toml [status] format = "i3bar" exec = "i3status" ``` outputs: kind: array items: ref: Output required: false description: | An array of output configurations. This can be used to configure outputs and create named outputs that can be referred to in actions. The configurations defined here will only be applied the first time matching outputs are connected to the compositor after the compositor has started. If you want change the configuration afterwards, use `jay randr` or a `configure-output` action. - Example: ```toml [[outputs]] name = "left" match.serial-number = "33K03894SL0" x = 0 y = 0 [[outputs]] name = "right" match.serial-number = "ETW1M02062SL0" x = 1920 y = 0 ``` connectors: kind: array items: ref: Connector required: false description: | An array of connector configurations. This can be used to configure connectors. The configurations defined here will only be applied when the connector is first discovered by the compositor. This usually never happens after the compositor has started unless you attach an external graphics card. - Example: ```toml [[connectors]] name = "eDP-1" enabled = false ``` workspace-capture: kind: boolean required: false description: | Configures whether newly created workspaces can be captured. The default is `true`. env: kind: map values: kind: string required: false description: | Defines environment variables that will be set for all applications. - Example: ```toml [env] GTK_THEME = "Adwaita:dark" ``` on-startup: ref: Action required: false description: | An action to execute as early as possible when the compositor starts. At this point, graphics have not yet been initialized. You should not use this to start graphical applications. See `on-graphics-initialized`. This setting has no effect during configuration reloads. keymaps: kind: array items: ref: Keymap required: false description: | Defines named keymaps. These keymaps can be used to easily switch between keymaps for different keyboards. - Example: ```toml keymap.name = "laptop" [shortcuts] alt-j = { type = "set-keymap", keymap.name = "laptop" } alt-k = { type = "set-keymap", keymap.name = "external" } [[keymaps]] name = "laptop" path = "./laptop-keymap.xkb" [[keymaps]] name = "external" path = "./external-keymap.xkb" ``` log-level: ref: LogLevel required: false description: | Sets the log level of the compositor. This setting cannot be changed by re-loading the configuration. Use `jay set-log-level` instead. - Example: ```toml log-level = "debug" ``` theme: ref: Theme required: false description: | Sets the theme of the compositor. gfx-api: ref: GfxApi required: false description: | Sets the graphics API used for newly discovered DRM devices. Changing this setting after the compositor has started usually has no effect unless you attach an external graphics card. Use `jay randr` to change the API used by individual devices at runtime. - Example: ```toml gfx-api = "Vulkan" ``` drm-devices: kind: array items: ref: DrmDevice required: false description: | Names and configures DRM devices. These settings are only applied to devices discovered after the configuration has been loaded. Therefore changing these settings usually has no effect at runtime unless you attach an external graphics card. You can use `jay randr` or a `configure-drm-device` Action to change these settings at runtime. - Example: ```toml render-device.name = "dedicated" [[drm-devices]] name = "dedicated" match = { pci-vendor = 0x1002, pci-model = 0x73ff } [[drm-devices]] name = "integrated" match = { pci-vendor = 0x1002, pci-model = 0x164e } gfx-api = "OpenGl" ``` direct-scanout: kind: boolean required: false description: | Configured whether the compositor attempts direct scanout. explicit-sync: kind: boolean required: false description: | Configures whether the compositor supports explicit sync. This cannot be changed after the compositor has started. The default is `true`. render-device: ref: DrmDeviceMatch required: false description: | Selects the device to use for rendering in a system with multiple GPUs. The first device that matches will be used. - Example: ```toml render-device.name = "dedicated" [[drm-devices]] name = "dedicated" match = { pci-vendor = 0x1002, pci-model = 0x73ff } ``` inputs: kind: array items: ref: Input required: false description: | Names and configures input devices. These settings are only applied to devices connected after the configuration has been loaded. You can apply setting without re-connecting the device by using `jay input` or a `configure-input` Action. - Example: ```toml render-device.name = "dedicated" [[inputs]] match.is-pointer = true left-handed = true transform-matrix = [[0.35, 0], [0, 0.35]] tap-enabled = true ``` on-idle: ref: Action required: false description: | An action to execute when the compositor becomes idle. - Example: ```toml on-idle = { type = "exec", exec = "lock" } ``` idle: ref: Idle required: false description: | The configuration of the idle timeout. Changing thise field after compositor startup has no effect. Use `jay idle` or a `configure-idle` action to change the idle timeout at runtime. - Example: ```toml idle.minutes = 10 ``` focus-follows-mouse: kind: boolean required: false description: | Configures whether moving the mouse over a window automatically moves the keyboard focus to that window. The default is `true`. window-management-key: kind: string required: false description: | Configures a key that will enable window management mode while pressed. In window management mode, floating windows can be moved by pressing the left mouse button and all windows can be resize by pressing the right mouse button. - Example: ```toml window-management-key = "Alt_L" ``` vrr: ref: Vrr required: false description: | Configures the default VRR settings. This can be overwritten for individual outputs. By default, the VRR mode is `never` and the cursor refresh rate is unbounded. - Example: ```toml vrr = { mode = "always", cursor-hz = 90 } ``` tearing: ref: Tearing required: false description: | Configures the default tearing settings. This can be overwritten for individual outputs. By default, the tearing mode is `variant3`. - Example: ```toml tearing.mode = "never" ``` libei: ref: Libei required: false description: | Configures the libei settings. - Example: ```toml libei.enable-socket = true ``` ui-drag: ref: UiDrag required: false description: | Configures the ui-drag settings. - Example: ```toml ui-drag = { enabled = false, threshold = 20 } ``` xwayland: ref: Xwayland required: false description: | Configures the Xwayland settings. - Example: ```toml xwayland = { scaling-mode = "downscaled" } ``` color-management: ref: ColorManagement required: false description: | Configures the color-management settings. - Example: ```toml [color-management] enabled = true ``` float: ref: Float required: false description: | Configures the settings of floating windows. - Example: ```toml [float] show-pin-icon = true ``` actions: kind: map values: ref: Action required: false description: | Named actions. Named actions can be used everywhere an action can be used. This can be used to avoid repeating the same action multiple times. - Example: ```toml actions.switch-to-1 = [ { type = "show-workspace", name = "1" }, { type = "define-action", name = "switch-to-next", action = "$switch-to-2" }, ] actions.switch-to-2 = [ { type = "show-workspace", name = "2" }, { type = "define-action", name = "switch-to-next", action = "$switch-to-3" }, ] actions.switch-to-3 = [ { type = "show-workspace", name = "3" }, { type = "define-action", name = "switch-to-next", action = "$switch-to-1" }, ] actions.switch-to-next = "$switch-to-1" [shortcuts] alt-x = "$switch-to-next" ``` max-action-depth: kind: number integer_only: true minimum: 0 required: false description: | The maximum call depth of named actions. This setting prevents infinite recursion when using named actions. Setting this value to 0 or less disables named actions completely. The default is `16`. clients: kind: array items: ref: ClientRule required: false description: | An array of client rules. These rules can be used to give names to clients and to manipulate them. - Example: ```toml [[clients]] name = "spotify" match.sandbox-app-id = "com.spotify.Client" ``` windows: kind: array items: ref: WindowRule required: false description: | An array of window rules. These rules can be used to give names to windows and to manipulate them. - Example: ```toml [[windows]] name = "spotify" match.title-regex = "Spotify" action = { type = "move-to-workspace", name = "music" } ``` pointer-revert-key: kind: string required: false description: | Sets the keysym that can be used to revert the pointer to the default state. Pressing this key cancels any grabs, drags, selections, etc. The default is `Escape`. Setting this to `NoSymbol` effectively disables this functionality. The value of the string should be the name of a keysym. The authoritative location for these names is [1] with the `XKB_KEY_` prefix removed. [1]: https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h - Example: ```toml pointer-revert-key = "NoSymbol" ``` use-hardware-cursor: kind: boolean required: false description: | Configures whether the default seat uses hardware cursors. The default is `true`. show-bar: kind: boolean required: false description: | Configures whether the built-in bar is shown. The default is `true`. focus-history: ref: FocusHistory required: false description: | Configures the focus-history settings. - Example: ```toml [focus-history] only-visible: true same-workspace: true ``` middle-click-paste: kind: boolean required: false description: | Configures whether middle-click pasting is enabled. Changing this has no effect on running applications. The default is `true`. modes: kind: map values: ref: InputMode required: false description: | Configures the input modes. Modes can be used to define shortcuts that are only active when the mode is active. - Example ```toml [modes."navigation".shortcuts] w = "focus-up" a = "focus-left" s = "focus-down" d = "focus-right" r = "focus-above" f = "focus-below" q = "focus-prev" e = "focus-next" ``` Modes can be activated with the `push-mode` and `latch-mode` actions. workspace-display-order: ref: WorkspaceDisplayOrder required: false description: | Configures the order of workspaces displayed. The default is `manual`. - Example: ```toml workspace-display-order = "sorted" ``` Idle: kind: table description: | The definition of an idle timeout. Omitted values are set to 0. If any value is explicitly set and all values are 0, the idle timeout is disabled. - Example: ```toml idle.minutes = 10 ``` fields: minutes: description: The number of minutes before going idle. kind: number integer_only: true minimum: 0 required: false seconds: description: The number of seconds before going idle. kind: number integer_only: true minimum: 0 required: false grace-period: description: | The grace period after the timeout expires. During the grace period, the screen goes black but the outputs are not yet disabled and the `on-idle` action does not yet run. This is a visual indicator that the system will soon get idle. The default is 5 seconds. ref: GracePeriod required: false GracePeriod: kind: table description: | The definition of a grace period. Omitted values are set to 0. If all values are 0, the grace period is disabled. - Example: ```toml idle.grace-period.seconds = 3 ``` fields: minutes: description: The number of minutes the grace period lasts. kind: number integer_only: true minimum: 0 required: false seconds: description: The number of seconds the grace period lasts. kind: number integer_only: true minimum: 0 required: false RepeatRate: kind: table description: | Describes a keyboard repeat rate. - Example: ```toml repeat-rate = { rate = 25, delay = 250 } ``` fields: rate: kind: number integer_only: true required: true description: The number of times to repeat per second. delay: kind: number integer_only: true required: true description: | The number of milliseconds after a key is pressed before repeating begins. ComplexShortcut: kind: table description: | Describes a complex shortcut. - Example: ```toml [complex-shortcuts.XF86AudioRaiseVolume] mod-mask = "alt" action = { type = "exec", exec = ["pactl", "set-sink-volume", "0", "+10%"] } ``` fields: mod-mask: kind: string required: false description: | The mod mask to apply to this shortcut. Should be a string containing modifiers concatenated by `-`. See the description of `Config.shortcuts` for more details. If this field is omitted, all modifiers are included in the mask. - Example: To raise the volume whenever the XF86AudioRaiseVolume key is pressed regardless of any modifiers except `alt`: ```toml [complex-shortcuts.XF86AudioRaiseVolume] mod-mask = "alt" action = { type = "exec", exec = ["pactl", "set-sink-volume", "0", "+10%"] } ``` Set `mod-mask = ""` to ignore all modifiers. action: ref: Action required: false description: | The action to execute. Omitting this is the same as setting it to `"none"`. latch: ref: Action required: false description: | An action to execute when the key is released. This registers an action to be executed when the key triggering the shortcut is released. The active modifiers are ignored for this purpose. - Example: To mute audio while the key is pressed: ```toml [complex-shortcuts.alt-x] action = { type = "exec", exec = ["pactl", "set-sink-mute", "0", "1"] } latch = { type = "exec", exec = ["pactl", "set-sink-mute", "0", "0"] } ``` Audio will be un-muted once `x` key is released, regardless of any other keys that are pressed at the time. Vrr: kind: table description: | Describes VRR settings. - Example: ```toml vrr = { mode = "always", cursor-hz = 90 } ``` fields: mode: ref: VrrMode required: false description: The VRR mode. cursor-hz: ref: VrrHz required: false description: | The VRR cursor refresh rate. Limits the rate at which cursors are updated on screen when VRR is active. VrrMode: description: | The VRR mode of an output. - Example: ```toml vrr = { mode = "always", cursor-hz = 90 } ``` kind: string values: - value: always description: VRR is never enabled. - value: never description: VRR is always enabled. - value: variant1 description: VRR is enabled when one or more applications are displayed fullscreen. - value: variant2 description: VRR is enabled when a single application is displayed fullscreen. - value: variant3 description: VRR is enabled when a single game or video is displayed fullscreen. VrrHz: description: | A VRR refresh rate limiter. - Example 1: ```toml vrr = { cursor-hz = 90 } ``` - Example 2: ```toml vrr = { cursor-hz = "none" } ``` kind: variable variants: - kind: string description: The string `none` can be used to disable the limiter. - kind: number description: The refresh rate in HZ. Tearing: kind: table description: | Describes tearing settings. - Example: ```toml tearing.mode = "never" ``` fields: mode: ref: TearingMode required: false description: The tearing mode. TearingMode: description: | The tearing mode of an output. - Example: ```toml tearing.mode = "never" ``` kind: string values: - value: always description: Tearing is never enabled. - value: never description: Tearing is always enabled. - value: variant1 description: Tearing is enabled when one or more applications are displayed fullscreen. - value: variant2 description: Tearing is enabled when a single application is displayed fullscreen. - value: variant3 description: | Tearing is enabled when a single application is displayed and the application has requested tearing. Libei: kind: table description: | Describes libei settings. - Example: ```toml libei.enable-socket = "true" ``` fields: enable-socket: kind: boolean required: false description: | Enables or disables the unauthenticated libei socket. Even if the socket is disabled, application can still request access via the portal. The default is `false`. Format: description: | A graphics format. These formats are documented in https://github.com/torvalds/linux/blob/master/include/uapi/drm/drm_fourcc.h - Example: ```toml [[outputs]] match.serial-number = "33K03894SL0" format = "rgb565" ``` kind: string values: - value: argb8888 description: "" - value: xrgb8888 description: "" - value: abgr8888 description: "" - value: xbgr8888 description: "" - value: r8 description: "" - value: gr88 description: "" - value: rgb888 description: "" - value: bgr888 description: "" - value: rgba4444 description: "" - value: rgbx4444 description: "" - value: bgra4444 description: "" - value: bgrx4444 description: "" - value: rgb565 description: "" - value: bgr565 description: "" - value: rgba5551 description: "" - value: rgbx5551 description: "" - value: bgra5551 description: "" - value: bgrx5551 description: "" - value: argb1555 description: "" - value: xrgb1555 description: "" - value: argb2101010 description: "" - value: xrgb2101010 description: "" - value: abgr2101010 description: "" - value: xbgr2101010 description: "" - value: abgr16161616 description: "" - value: xbgr16161616 description: "" - value: abgr16161616f description: "" - value: xbgr16161616f description: "" UiDrag: kind: table description: | Describes ui-drag settings. - Example: ```toml ui-drag = { enabled = false, threshold = 20 } ``` fields: enabled: kind: boolean required: false description: | Enables or disables dragging of tiles and workspaces. The default is `true`. threshold: kind: number integer_only: true required: false description: | Sets the distance at which ui dragging starts. The default is `10`. Xwayland: kind: table description: | Describes Xwayland settings. - Example: ```toml xwayland = { scaling-mode = "downscaled" } ``` fields: scaling-mode: ref: XScalingMode required: false description: The scaling mode of X windows. XScalingMode: description: | The scaling mode of X windows. - Example: ```toml xwayland = { scaling-mode = "downscaled" } ``` kind: string values: - value: default description: | The default mode. Currently this means that windows are rendered at the lowest scale and then upscaled if necessary. - value: downscaled description: | Windows are rendered at the highest integer scale and then downscaled. This has significant performance implications unless the window is running on the output with the highest scale and that scale is an integer scale. For example, on a 3840x2160 output with a 1.5 scale, a fullscreen window will be rendered at 3840x2160 * 2 / 1.5 = 5120x2880 pixels and then downscaled to 3840x2160. This overhead gets worse the lower the scale of the output is. Additionally, this mode requires the X window to scale its contents itself. In the example above, you might achieve this by setting the environment variable `GDK_SCALE=2`. ColorManagement: kind: table description: | Describes color-management settings. - Example: ```toml [color-management] enabled = true ``` fields: enabled: description: | Whether the color management protocol is enabled. This has no effect on running applications. The default is `false`. kind: boolean required: false ColorSpace: description: | The color space of an output. kind: string values: - value: default description: The default color space (usually sRGB). - value: bt2020 description: The BT.2020 color space. TransferFunction: description: | The transfer function of an output. kind: string values: - value: default description: The default transfer function (usually sRGB). - value: pq description: The PQ transfer function. Brightness: kind: variable description: | The brightness setting of an output. variants: - kind: string description: | The default brightness setting. values: - value: default description: | The default brightness setting. The behavior depends on the transfer function: - `default`: The maximum brightness of the output. - `PQ`: 203 cd/m^2 - kind: number description: | The brightness in cd/m^2. Float: kind: table description: | Describes settings of floating windows. - Example: ```toml [float] show-pin-icon = true ``` fields: show-pin-icon: description: | Sets whether floating windows always show a pin icon. The default is `false`. kind: boolean required: false ClientRule: kind: table description: | A client rule. fields: name: kind: string required: false description: | The name of this rule. This name can be referenced in other rules. - Example ```toml [[clients]] name = "spotify" match.sandbox-app-id = "com.spotify.Client" [[clients]] match.name = "spotify" action = "kill-client" ``` match: ref: ClientMatch required: false description: The criteria that select the client that this rule applies to. action: ref: Action required: false description: An action to execute when a client matches the criteria. latch: ref: Action required: false description: An action to execute when a client no longer matches the criteria. ClientMatch: kind: table description: | Criteria for matching clients. If no fields are set, all clients are matched. If multiple fields are set, all fields must match the client. fields: name: kind: string required: false description: | Matches if the client rule with this name matches. - Example: ```toml [[clients]] name = "spotify" match.sandbox-app-id = "com.spotify.Client" # Matches the same clients as the previous rule. [[clients]] match.name = "spotify" ``` not: ref: ClientMatch required: false description: | Matches if the contained criteria don't match. - Example: ```toml [[clients]] name = "not-spotify" match.not.sandbox-app-id = "com.spotify.Client" ``` all: kind: array items: ref: ClientMatch required: false description: | Matches if all of the contained criteria match. - Example: ```toml [[clients]] match.all = [ { sandbox-app-id = "com.spotify.Client" }, { sandbox-engine = "org.flatpak" }, ] ``` any: kind: array items: ref: ClientMatch required: false description: | Matches if any of the contained criteria match. - Example: ```toml [[clients]] match.any = [ { sandbox-app-id = "com.spotify.Client" }, { sandbox-app-id = "com.valvesoftware.Steam" }, ] ``` exactly: ref: ClientMatchExactly required: false description: | Matches if a specific number of contained criteria match. - Example: ```toml # Matches any client that is either steam or sandboxed by flatpak but not both. [[clients]] match.exactly.num = 1 match.exactly.list = [ { sandbox-engine = "org.flatpak" }, { sandbox-app-id = "com.valvesoftware.Steam" }, ] ``` sandboxed: kind: boolean required: false description: | Matches if the client is/isn't sandboxed. - Example: ```toml [[clients]] match.sandboxed = true ``` sandbox-engine: kind: string required: false description: | Matches the engine name of the client's sandbox verbatim. - Example: ```toml [[clients]] match.sandbox-engine = "org.flatpak" ``` sandbox-engine-regex: kind: string required: false description: | Matches the engine name of the client's sandbox with a regular expression. - Example: ```toml [[clients]] match.sandbox-engine = "flatpak" ``` sandbox-app-id: kind: string required: false description: | Matches the app id of the client's sandbox verbatim. - Example: ```toml [[clients]] match.sandbox-app-id = "com.spotify.Client" ``` sandbox-app-id-regex: kind: string required: false description: | Matches the app id of the client's sandbox with a regular expression. - Example: ```toml [[clients]] match.sandbox-app-id-regex = "(?i)spotify" ``` sandbox-instance-id: kind: string required: false description: | Matches the instance id of the client's sandbox verbatim. sandbox-instance-id-regex: kind: string required: false description: | Matches the instance id of the client's sandbox with a regular expression. uid: kind: number integer_only: true required: false description: Matches the user ID of the client. pid: kind: number integer_only: true required: false description: Matches the process ID of the client. is-xwayland: kind: boolean required: false description: Matches if the client is/isn't Xwayland. comm: kind: string required: false description: Matches the `/proc/pid/comm` of the client verbatim. comm-regex: kind: string required: false description: Matches the `/proc/pid/comm` of the client with a regular expression. exe: kind: string required: false description: Matches the `/proc/pid/exe` of the client verbatim. exe-regex: kind: string required: false description: Matches the `/proc/pid/exe` of the client with a regular expression. ClientMatchExactly: kind: table description: | Criterion for matching a specific number of client criteria. fields: num: kind: number required: true description: The number of criteria that must match. list: kind: array items: ref: ClientMatch required: true description: The list of criteria. WindowRule: kind: table description: | A window rule. fields: name: kind: string required: false description: | The name of this rule. This name can be referenced in other rules. - Example ```toml [[windows]] name = "spotify" match.title-regex = "Spotify" [[windows]] match.name = "spotify" action = "enter-fullscreen" ``` match: ref: WindowMatch required: false description: The criteria that select the window that this rule applies to. action: ref: Action required: false description: An action to execute when a window matches the criteria. latch: ref: Action required: false description: An action to execute when a window no longer matches the criteria. auto-focus: kind: boolean required: false description: | Whether newly mapped windows that match this rule get the keyboard focus. If a window matches any rule for which this is false, the window will not be automatically focused. initial-tile-state: ref: TileState required: false description: Specifies if the window is initially mapped tiled or floating. WindowMatch: kind: table description: | Criteria for matching windows. If no fields are set, all windows are matched. If multiple fields are set, all fields must match the window. fields: name: kind: string required: false description: | Matches if the window rule with this name matches. - Example: ```toml [[windows]] name = "spotify" match.title-regex = "Spotify" # Matches the same windows as the previous rule. [[windows]] match.name = "spotify" ``` not: ref: WindowMatch required: false description: | Matches if the contained criteria don't match. - Example: ```toml [[windows]] name = "not-spotify" match.not.title-regex = "Spotify" ``` all: kind: array items: ref: WindowMatch required: false description: | Matches if all of the contained criteria match. - Example: ```toml [[windows]] match.all = [ { title-regex = "Spotify" }, { title-regex = "Premium" }, ] ``` any: kind: array items: ref: WindowMatch required: false description: | Matches if any of the contained criteria match. - Example: ```toml [[windows]] match.any = [ { title-regex = "Spotify" }, { title-regex = "Alacritty" }, ] ``` exactly: ref: WindowMatchExactly required: false description: | Matches if a specific number of contained criteria match. - Example: ```toml # Matches any window that is either Alacritty or on workspace 3 but not both. [[windows]] match.exactly.num = 1 match.exactly.list = [ { workspace = "3" }, { title-regex = "Alacritty" }, ] ``` types: ref: WindowTypeMask required: false description: Matches windows whose type is contained in the mask. client: ref: ClientMatch required: false description: Matches if the window's client matches the client criterion. title: kind: string required: false description: Matches the title of the window verbatim. title-regex: kind: string required: false description: Matches the title of the window with a regular expression. app-id: kind: string required: false description: Matches the app-id of the window verbatim. app-id-regex: kind: string required: false description: Matches the app-id of the window with a regular expression. floating: kind: boolean required: false description: Matches if the window is/isn't floating. visible: kind: boolean required: false description: Matches if the window is/isn't visible. urgent: kind: boolean required: false description: Matches if the window has/hasn't the urgency flag set. focused: kind: boolean required: false description: Matches if the window has/hasn't the keyboard focus. fullscreen: kind: boolean required: false description: Matches if the window is/isn't fullscreen. just-mapped: kind: boolean required: false description: | Matches if the window has/hasn't just been mapped. This is true for one iteration of the compositor's main loop immediately after the window has been mapped. tag: kind: string required: false description: Matches the toplevel-tag of the window verbatim. tag-regex: kind: string required: false description: Matches the toplevel-tag of the window with a regular expression. x-class: kind: string required: false description: Matches the X class of the window verbatim. x-class-regex: kind: string required: false description: Matches the X class of the window with a regular expression. x-instance: kind: string required: false description: Matches the X instance of the window verbatim. x-instance-regex: kind: string required: false description: Matches the X instance of the window with a regular expression. x-role: kind: string required: false description: Matches the X role of the window verbatim. x-role-regex: kind: string required: false description: Matches the X role of the window with a regular expression. workspace: kind: string required: false description: Matches the workspace of the window verbatim. workspace-regex: kind: string required: false description: Matches the workspace of the window with a regular expression. content-types: ref: ContentTypeMask required: false description: Matches windows whose content type is contained in the mask. WindowMatchExactly: kind: table description: | Criterion for matching a specific number of window criteria. fields: num: kind: number required: true description: The number of criteria that must match. list: kind: array items: ref: WindowMatch required: true description: The list of criteria. WindowTypeMask: description: | A mask of window types. kind: variable variants: - kind: string description: A named mask. values: - value: none description: The empty mask. - value: any description: The mask containing every possible type. - value: container description: The mask matching a container. - value: xdg-toplevel description: The mask matching an XDG toplevel. - value: x-window description: The mask matching an X window. - value: client-window description: The mask matching any type of client window. - kind: array description: An array of masks that are OR'd. items: ref: WindowTypeMask TileState: description: Whether a window is tiled or floating. kind: string values: - value: tiled description: The window is tiled. - value: floating description: The window is floating. ContentTypeMask: description: | A mask of content types. kind: variable variants: - kind: string description: A named mask. values: - value: none description: The mask matching windows without a content type. - value: any description: The mask containing every possible type except `none`. - value: photo description: The mask matching photo content. - value: video description: The mask matching video content. - value: game description: The mask matching game content. - kind: array description: An array of masks that are OR'd. items: ref: ContentTypeMask FocusHistory: kind: table description: | Describes settings of the focus history. - Example: ```toml [focus-history] only-visible: true same-workspace: true ``` fields: only-visible: description: | Sets whether the focus history only moves to windows that are already visible. If this is false, then the window will be made visible before focusing it. The default is `false`. kind: boolean required: false same-workspace: description: | Sets whether the focus history only moves to windows on the same workspace. The default is `false`. kind: boolean required: false MarkId: kind: table description: | Identifies a mark. Exactly one of the fields must be set. - Example: ```toml [shortcuts] alt-x = { type = "create-mark", id.key = "a" } ``` fields: key: description: | Identifies a mark by a key press. The names of the keys can be found in [1] with the `KEY_` prefix removed. The key names must be written all lowercase. [1]: https://github.com/torvalds/linux/blob/master/include/uapi/linux/input-event-codes.h kind: string required: false name: description: | Identifies a mark with an arbitrary string. kind: string required: false InputMode: kind: table description: | Defines an input mode. Modes can be used to define shortcuts that are only active when the mode is active. - Example ```toml [modes."navigation".shortcuts] w = "focus-up" a = "focus-left" s = "focus-down" d = "focus-right" r = "focus-above" f = "focus-below" q = "focus-prev" e = "focus-next" ``` fields: parent: kind: string required: false description: | The parent of this input mode. This mode inherits all shortcuts from this parent. If this field is not set, then it inherits the shortcuts from the top-level shortcuts. Note that you can disable a shortcut by explicitly assigning it the action `none`. shortcuts: kind: map values: ref: Action required: false description: | The shortcuts of this mode. See the same field in the top-level `Config` object for a description. complex-shortcuts: kind: map values: ref: ComplexShortcut required: false description: | The complex shortcuts of this mode. See the same field in the top-level `Config` object for a description. WorkspaceDisplayOrder: kind: string description: | The order of workspaces displayed. values: - value: manual description: Workspaces are not sorted and can be manually dragged. - value: sorted description: Workspaces are sorted alphabetically and cannot be manually dragged.