xkbcommon is a keyboard keymap compiler and support library which processes keymaps as defined by the XKB (X Keyboard Extension) specification (minus some legacy features). It also contains a module for handling Compose and dead keys, a separate registry library for listing available keyboard layouts and a fair set of <abbr title="Command-Line Interface">CLI</abbr> --> tools to support keyboard layouts development.

xkbcommon is the standard keymap handling library on Wayland and is used by compositors, toolkits, and applications to handle keyboard state and translate key events into characters and actions.

Quick Guide

Introduction to XKB

See Introduction to XKB for the essentials of XKB concepts and how a keymap is built.

Features

xkbcommon implements most of the XKB specification, except for some obscure features. xkbcommon has notable additions that lift hard-coded limitation of the X11 Protocol (e.g. keycodes and modifiers).

See the Compatibility page for further details.

Using the library

Library quick guide

Introduction on how to use this library

API Documentation

Full API reference.

While libxkbcommon’s API is somewhat derived from the classic XKB API as found in X11/extensions/XKB.h and friends, it has been substantially reworked to expose fewer internal details to clients.

Release notes

History of the xkbcommon changes by version

FAQ

Frequently Asked Questions

Developing keyboard layouts

Custom layouts

Quick start for adding a custom layout or option

Keymap format

Documentation of keymap components and keymap text syntax

Tools

xkbcommon offers a set of <abbr title="Command-Line Interface">CLI</abbr> tools, grouped under the xkbcli application. -->

FAQ

Frequently Asked Questions

Building

xkbcommon is built with Meson:

meson setup build
meson compile -C build
meson test -C build

See the building guide for dependencies and configuration options.

Layouts database

xkbcommon does not distribute a keyboard layout dataset itself, other than for testing purposes. The most common dataset is xkeyboard-config, which is used by all current distributions for their XKB data. Further information on xkeyboard-config is available at its homepage and at its repository.

The dataset for Compose is distributed in libX11, as part of the X locale data.

Development

Project’s homepage

https://xkbcommon.org

Repository

https://github.com/xkbcommon/libxkbcommon

Contributions

Patches are always welcome, and may be filed at:

GitHub pull request (preferred)
wayla.nosp@m.nd-d.nosp@m.evel@.nosp@m.list.nosp@m.s.fre.nosp@m.edes.nosp@m.ktop..nosp@m.org

Bug reports, questions

Bug reports and questions are also welcome, and may be filed at GitHub.

For general topics, prefer opening a discussion.

Maintainers

License

See the LICENSE file.

Credits

Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon off the ground initially.