Jun Aruga's Blog

Output, activities, memo and etc.

i3: Customize keyboard layout on X based window manager

This blog is to summarize the outcome of communication[1] in the xkeyboard-config project through my pull request. Thanks for the help!

On Wayland-based window managers such as Sway, people can customize keyboard layout freely under their home directory by xkbcommon[2].

However, on X server-based window manager such as i3, I didn't know the way. The solution is to use "custom" keyboard layout (Option "XkbLayout" "custom").[3]

Create the following file. The line key <ESC> ... is my customization, assigning Shift+ESC as Compose key.

$ cat /usr/share/X11/xkb/symbols/custom 
xkb_symbols "basic" {
    include "us(basic)"
    // Shift + ESC as Compose key.
    key <ESC> { type[Group1]="TWO_LEVEL", [ Escape, Multi_key ] };

According to the document [4][5], the TWO_LEVEL means the key itself without modifiers except for the shift key, and the shift key + the key.

Here is my current custom keyboard file with the Option "XkbLayout" "custom".

$ cat /etc/X11/xorg.conf.d/01-custom-keyboard.conf
Section "InputClass"
        Identifier "system-keyboard"
        MatchIsKeyboard "on"
        # /usr/share/X11/xkb/symbols/custom
        Option "XkbLayout" "custom"
        Option "XkbVariant" ","
        # /usr/share/X11/xkb/rules/evdev
        # /usr/share/X11/xkb/symbols/capslock
        # /usr/share/X11/xkb/symbols/compose
        # The caps:escape_shifted_compose is available on xkeyboard-config >= 2.35.
        # https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/commit/8018e2982d1067fc79195e518546fee191b63b6d
        Option "XkbOptions" "caps:escape_shifted_compose"

If you want to test your custom keyboard layout, the following commands help.

$ setxkbmap -layout custom
$ setxkbmap -query
rules:      evdev
model:      pc105
layout:     custom
variant:    ,
options:    caps:escape_shifted_compose

As troubleshooting. I was running the following command in the initial process of the i3. And the fcitx5 was overriding the keyboard layout (XkbLayout) and variant (XkbVariant) with the layout: us.

$ cat home/.config/i3/config
exec --no-startup-id fcitx5 -d

The solution is to run fcitx5-configtool and uncheck Addons => XCB => Allow Overriding System XKB Settings [6]. Here is the setting.

$ cat ~/.config/fcitx5/conf/xcb.conf 
# Allow Overriding System XKB Settings
Allow Overriding System XKB Settings=False
# Always set layout to be only group layout