Skip to main content
Version: 2.1

Keyboard Layout Switching

Configure a comma-separated list of layouts in rc.lua, then register a keybinding to cycle through them.

Setting Your Layout​

local awful = require("awful")
awful.input.xkb_layout = "us,de,ru"
awful.input.xkb_variant = ",nodeadkeys,"
awful.input.xkb_options = "ctrl:nocaps,compose:ralt"

Variant positions correspond to layout positions. Here, only German uses a variant. For one layout, set xkb_layout = "us" and leave xkb_variant empty.

Switching Layouts​

In SomeWM 2.1, use an explicit binding instead of relying on grp:* toggle options. This is a SomeWM implementation limitation, not a general restriction of Wayland.

awful.keyboard.append_global_keybindings({
awful.key({ "Mod1", "Shift" }, "space", function()
local layouts = awful.widget.keyboardlayout.get_groups_from_group_names(
awesome.xkb_get_group_names())
if not layouts or #layouts == 0 then return end
local current = awesome.xkb_get_layout_group()
awesome.xkb_set_layout_group((current + 1) % #layouts)
end, { description = "switch keyboard layout", group = "awesome" }),
})

Press Alt+Shift+Space to advance through the configured layouts. Group indices start at zero.

Displaying Current Layout​

Create an indicator inside your screen decoration handler and add it to the existing wibar's widget layout:

local keyboard_layout = awful.widget.keyboardlayout()

The widget updates when the active group changes. Clicking it also cycles layouts.

XKB Options That Work​

Static mappings can be combined in xkb_options, as in the first example:

OptionMapping
ctrl:nocapsCaps Lock becomes Control
ctrl:swapcapsSwap Caps Lock and Control
compose:raltRight Alt becomes Compose
caps:escapeCaps Lock becomes Escape

Choose one Caps Lock mapping. Each assignment replaces the whole option string.

See Also​