Skip to content
Overview
Configuration Reference
Keyboard Layout

Keyboard Layout

SamWM supports multiple keyboard layouts with per-workspace switching.

Configuration 

samwm.input({
    keyboard = {
        -- Keyboard model
        xkb_model = "",

        -- Layout variants
        xkb_layout = "us,ar",

        -- Layout options
        xkb_options = "grp:alt_shift_toggle",

        -- Repeat rate and delay
        repeat_rate = 50,
        repeat_delay = 300,

        -- Numlock state
        numlock = true,
    }
})

Per-Workspace Layouts

Set different keyboard layouts per workspace:

-- Workspace 1: English
samwm.workspace_layout(1, "us")

-- Workspace 2: Arabic
samwm.workspace_layout(2, "ar")

-- Workspace 3: English + Russian
samwm.workspace_layout(3, "us,ru")

Switching Layouts

Keybindings 

-- Super + Space: Cycle through layouts
samwm.bind("SUPER", "space", "layout next", "Next keyboard layout")

-- Super + Shift + Space: Previous layout
samwm.bind("SUPER+SHIFT", "space", "layout prev", "Previous keyboard layout")

-- Super + 1-9: Switch to specific layout
samwm.bind("SUPER", "1", "layout 1", "English")
samwm.bind("SUPER", "2", "layout 2", "Arabic")

Via IPC 

samwm-msg layout next
samwm-msg layout 1

XKB Options

Common xkb_options:

Option Description
grp:alt_shift_toggle Alt+Shift to switch layouts
grp:ctrl_alt_toggle Ctrl+Alt to switch
grp:menu_toggle Menu key to switch
grp:win_space Win+Space to switch
caps:escape Caps Lock as Escape
ctrl:nocaps Caps Lock as Ctrl
compose:ralt Right Alt as Compose

Lua API

Get Current Layout 

local layout = samwm.get_keyboard_layout()
print("Current:", layout.current)
print("Index:", layout.index)

Set Layout by Index 

samwm.set_keyboard_layout(1) -- Second layout

Set Layout by Name 

samwm.set_keyboard_layout("ar") -- Arabic

List Available Layouts 

local layouts = samwm.list_keyboard_layouts()
for i, layout in ipairs(layouts) do
    print(i, layout.name, layout.description)
end

Event Hooks 

-- On layout change
samwm.on("keyboard_layout_change", function(layout)
    print("Layout changed to:", layout.name)
    -- Update waybar indicator
end)

Waybar Integration 

"keyboard-state": {
    "format": "{symbol}",
    "format-icons": ["us", "ar"],
    "exec": "samwm-msg keyboard-layout",
    "interval": 1,
    "return-type": "json",
    "on-click": "samwm-msg layout next"
}

Multi-Language Setup 

-- English (default)
samwm.input({
    keyboard = {
        xkb_layout = "us",
    }
})

-- Add more languages
samwm.add_keyboard_layout("ar") -- Arabic
samwm.add_keyboard_layout("ru") -- Russian
samwm.add_keyboard_layout("de") -- German

-- Configure switching
samwm.general({
    keyboard_options = "grp:alt_shift_toggle"
})

Troubleshooting

Layout not switching

  • Check xkb_layout is spelled correctly
  • Verify XKB symbols are installed: xkbcomp -xkb $DISPLAY /dev/null

Layout doesn’t persist

  • Layout resets on workspace switch (expected behavior)
  • Use per-workspace layout config to maintain state

Wrong characters

  • Make sure the correct XKB keymap is loaded
  • Check setxkbmap -query to see current settings
Idle & DPMSMulti-Monitor