instantWM Configuration

instantWM is customized through a TOML configuration file at ~/.config/instantwm/config.toml.

After editing the config file, you can either restart instantWM or use instantwmctl to apply changes dynamically for certain settings.

Configuration File Location

~/.config/instantwm/config.toml

If the file doesn't exist, instantWM will use sensible defaults.

Full Configuration Example

# Fonts - first font is primary, others are fallbacks
fonts = ["Cantarell-Regular:size=12", "JetBrains Mono:size=11"]

# Color configuration
[colors.tag.normal]
inactive = { fg = "#DFDFDF", bg = "#121212", detail = "#121212" }
filled = { fg = "#DFDFDF", bg = "#384252", detail = "#89B3F7" }
focus = { fg = "#121212", bg = "#89B3F7", detail = "#89B3F7" }
nofocus = { fg = "#DFDFDF", bg = "#292F3A", detail = "#3E485B" }
empty = { fg = "#5E6572", bg = "#121212", detail = "#121212" }

[colors.tag.hover]
inactive = { fg = "#DFDFDF", bg = "#1E2229", detail = "#1E2229" }
filled = { fg = "#DFDFDF", bg = "#4A5568", detail = "#A7BDD9" }
focus = { fg = "#121212", bg = "#A7BDD9", detail = "#A7BDD9" }
nofocus = { fg = "#DFDFDF", bg = "#353D4B", detail = "#475166" }
empty = { fg = "#6E7889", bg = "#1E2229", detail = "#1E2229" }

[colors.window.normal]
focus = { fg = "#DFDFDF", bg = "#292F3A", detail = "#3E485B" }
normal = { fg = "#6E7889", bg = "#292F3A", detail = "#3E485B" }
minimized = { fg = "#6E7889", bg = "#121212", detail = "#121212" }
sticky = { fg = "#F9D71C", bg = "#292F3A", detail = "#3E485B" }
sticky_focus = { fg = "#121212", bg = "#F9D71C", detail = "#F9D71C" }
overlay = { fg = "#89B3F7", bg = "#292F3A", detail = "#3E485B" }
overlay_focus = { fg = "#121212", bg = "#89B3F7", detail = "#89B3F7" }

[colors.window.hover]
focus = { fg = "#DFDFDF", bg = "#353D4B", detail = "#475166" }
normal = { fg = "#7E8899", bg = "#353D4B", detail = "#475166" }
minimized = { fg = "#7E7889", bg = "#1E2229", detail = "#1E2229" }
sticky = { fg = "#F9D71C", bg = "#353D4B", detail = "#475166" }
sticky_focus = { fg = "#121212", bg = "#F9D71C", detail = "#F9D71C" }
overlay = { fg = "#89B3F7", bg = "#353D4B", detail = "#475166" }
overlay_focus = { fg = "#121212", bg = "#89B3F7", detail = "#89B3F7" }

[colors.close_button.normal]
normal = { fg = "#6E7889", bg = "#292F3A", detail = "#3E485B" }
locked = { fg = "#6E7889", bg = "#292F3A", detail = "#3E485B" }
fullscreen = { fg = "#F9D71C", bg = "#292F3A", detail = "#3E485B" }

[colors.close_button.hover]
normal = { fg = "#DFDFDF", bg = "#81C995", detail = "#5EA984" }
locked = { fg = "#DFDFDF", bg = "#E16A98", detail = "#B7416E" }
fullscreen = { fg = "#121212", bg = "#F9D71C", detail = "#D4A61A" }

[colors.border]
normal = "#384252"
tile_focus = "#89B3F7"
float_focus = "#81C995"
snap = "#FDD663"

[colors.status]
fg = "#DFDFDF"
bg = "#121212"
detail = "#3E485B"

# Keyboard layout configuration
[keyboard]
layouts = ["us", "de"]
variant = ["", "nodeadkeys"]
options = "compose:ralt"

# Input configuration (touchpad, mouse, etc.)
[input]
# Example: enable tap-to-click on touchpads
# [input.type:touchpad]
# tap = "enabled"
# natural_scroll = "enabled"

# Custom keybinds
[[keybinds]]
modifiers = ["Super"]
key = "Return"
action = { spawn = ["alacritty"] }

[[keybinds]]
modifiers = ["Super", "Shift"]
key = "q"
action = "kill"

[[keybinds]]
modifiers = ["Super"]
key = "F3"
action = "next_keyboard_layout"

# Desktop keybinds (work without a focused window)
[[desktop_keybinds]]
modifiers = ["Super"]
key = "d"
action = { spawn = ["instantmenu"] }

Color Schemes

Each color property has normal and hover variants that switch when hovered with the mouse.

Color Types

Each element has three colors:

• fg (foreground): text color
• bg (background): behind the text
• detail: shading details below the element

Element Types

Element	Description
tag	Tag number indicator
window	Window title
close_button	Close button on active window title
border	Window border colors
status	Status bar text

Color States

Tags:

• inactive: Tag not selected, no windows
• filled: Tag has windows but none focused
• focus: Tag selected and has focused window
• nofocus: Tag not selected but has windows
• empty: Tag selected but no windows

Windows:

• focus: Currently focused window
• normal: Regular unfocused window
• minimized: Minimized window
• sticky: Sticky window (visible on all tags)
• sticky_focus: Sticky window that is focused
• overlay: Window on overlay
• overlay_focus: Focused window on overlay

Close Button:

• normal: Default close button
• locked: Locked window close button
• fullscreen: Fullscreen window close button

Border:

• normal: Unfocused window border
• tile_focus: Focused tiled window border
• float_focus: Focused floating window border
• snap: Snapped window border

Keyboard Configuration

The [keyboard] section configures XKB keyboard layouts:

[keyboard]
layouts = ["us", "de", "fr"]     # Layout names
variant = ["", "nodeadkeys", ""]  # Per-layout variants
options = "compose:ralt"          # XKB options
model = "pc105"                   # Keyboard model (optional)

Input Configuration

Configure touchpad and mouse settings:

# Global settings
[input]
[input.type:touchpad]
tap = "enabled"
natural_scroll = "enabled"
accel_profile = "adaptive"
pointer_accel = 0.5

[input.type:mouse]
pointer_accel = 0.3

Valid values:

• tap: "enabled" or "disabled"
• natural_scroll: "enabled" or "disabled"
• accel_profile: "flat" or "adaptive"
• pointer_accel: Floating point number

Custom Keybinds

Add or override keybindings:

# Spawn a command
[[keybinds]]
modifiers = ["Super"]
key = "Return"
action = { spawn = ["alacritty"] }

# Named actions
[[keybinds]]
modifiers = ["Super", "Shift"]
key = "q"
action = "kill"

# Remove a default binding
[[keybinds]]
modifiers = ["Super"]
key = "f"
action = { unbind = true }

# Set layout
[[keybinds]]
modifiers = ["Super"]
key = "t"
action = { set_layout = "tile" }

# Adjust master window count
[[keybinds]]
modifiers = ["Super"]
key = "i"
action = { inc_nmaster = 1 }

# Adjust master window factor
[[keybinds]]
modifiers = ["Super"]
key = "h"
action = { set_mfact = -0.05 }

Available Modifiers

• Super or Mod4 - Windows/Super key
• Shift - Shift key
• Ctrl or Control - Control key
• Alt or Mod1 - Alt key

Available Actions

Window Management:

• zoom - Focus next window in stack
• kill - Close focused window
• shut_kill - Force close (SIGKILL)
• toggle_fullscreen - Toggle fullscreen
• toggle_maximized - Toggle maximized floating
• center_window - Center floating window

Focus:

• focus_next / focus_prev - Next/previous window
• focus_up / focus_down / focus_left / focus_right - Directional focus
• focus_last - Focus previously focused window

Layouts:

• layout_tile / layout_float / layout_monocle / layout_grid - Set layout
• toggle_layout - Toggle between current and previous layout
• cycle_layout_next / cycle_layout_prev - Cycle layouts

Master Area:

• inc_nmaster / dec_nmaster - Increase/decrease master windows
• mfact_grow / mfact_shrink - Adjust master area size

Tags:

• view_all - Show all tags
• tag_all - Send window to all tags
• scroll_left / scroll_right - Switch tags
• shift_tag_left / shift_tag_right - Move window to adjacent tag
• shift_view_left / shift_view_right - Move view to adjacent tag

Monitoring:

• focus_mon_next / focus_mon_prev - Next/previous monitor
• follow_mon_next / follow_mon_prev - Move window and follow to next/previous monitor

Special Features:

• toggle_overview - Toggle overview mode
• toggle_sticky - Toggle sticky (visible on all tags)
• toggle_bar - Toggle status bar
• create_overlay - Create overlay from selected window
• scratchpad_toggle - Toggle scratchpad
• scratchpad_make - Make window a scratchpad
• next_keyboard_layout / prev_keyboard_layout - Switch keyboard layout

Listing Available Actions

To see all available actions for keybindings:

instantwm --list-actions

This outputs a table of all actions with their descriptions and argument examples.

You can also get JSON output:

instantwm --list-actions --json

Runtime Control

instantWM provides the instantwmctl command-line tool for runtime control. See the instantwmctl documentation for a complete reference.

instantWM reads status text from the X11 root window name property (X11) or writes to the status bar directly (Wayland). Configure a status command in your config:

status_command = "i3status-rs"

Or set status manually:

instantwmctl update-status "My Status"

Custom Modes

Create sway-like modes with their own keybindings:

[modes.resize]
description = "Resize"

[[modes.resize.keybinds]]
key = "h"
action = { set_mfact = -0.05 }

[[modes.resize.keybinds]]
key = "l"
action = { set_mfact = 0.05 }

[[modes.resize.keybinds]]
key = "j"
action = { focus_stack = "next" }

[[modes.resize.keybinds]]
key = "k"
action = { focus_stack = "prev" }

[[modes.resize.keybinds]]
key = "Escape"
action = { set_mode = "default" }

[[modes.resize.keybinds]]
key = "Return"
action = { set_mode = "default" }

Then bind a key to enter the mode:

[[keybinds]]
modifiers = ["Super"]
key = "r"
action = { set_mode = "resize" }

Monitor Configuration

Configure specific monitor settings:

[monitors "DP-1"]
resolution = "1920x1080"
refresh_rate = 144.0
position = "0,0"
scale = 1.0
enable = true

[monitors "HDMI-A-1"]
position = "left-of:DP-1"

Position can be specified as:

• Absolute: "X,Y" (e.g., "1920,0")
• Relative: "left-of:OUTPUT", "right-of:OUTPUT", "above:OUTPUT", "below:OUTPUT"

Configuration Includes

Split your configuration into multiple files:

# Main config
[[includes]]
file = "keybinds.toml"

[[includes]]
file = "colors.toml"

The included files will be merged with the main configuration.

Xresources (Legacy)

For backwards compatibility, instantWM still supports the old Xresources configuration. However, the TOML configuration is recommended for new setups.

The old syntax:

instantwm.parameter: value

After editing ~/.Xresources, run xrdb ~/.Xresources and restart instantWM.