Skip to main content

Display Configuration

See the displays feature page for more details.

See Configuration Overview for instructions on how to change these settings.

Kconfig

Definition files:

ConfigTypeDescriptionDefault
CONFIG_ZMK_DISPLAYboolEnable support for displaysn
CONFIG_ZMK_WIDGET_LAYER_STATUSboolEnable a widget to show the highest, active layery
CONFIG_ZMK_WIDGET_BATTERY_STATUSboolEnable a widget to show battery charge informationy
CONFIG_ZMK_WIDGET_BATTERY_STATUS_SHOW_PERCENTAGEboolIf battery widget is enabled, show percentage instead of iconsn
CONFIG_ZMK_WIDGET_OUTPUT_STATUSboolEnable a widget to show the current output (USB/BLE)y
CONFIG_ZMK_WIDGET_WPM_STATUSboolEnable a widget to show words per minuten

If CONFIG_ZMK_DISPLAY is enabled, exactly zero or one of the following options must be set to y. The first option is used if none are set.

ConfigDescription
CONFIG_ZMK_DISPLAY_STATUS_SCREEN_BUILT_INUse the built-in status screen
CONFIG_ZMK_DISPLAY_STATUS_SCREEN_CUSTOMUse a custom status screen

If CONFIG_ZMK_DISPLAY is enabled, exactly zero or one of the following options must be set to y. The first option is used if none are set.

ConfigDescription
CONFIG_ZMK_DISPLAY_WORK_QUEUE_SYSTEMUse the system main thread for UI updates
CONFIG_ZMK_DISPLAY_WORK_QUEUE_DEDICATEDUse a dedicated thread for UI updates

Using a dedicated thread requires more memory but prevents displays with slow updates (e.g. E-paper) from delaying key scanning and other processes. If enabled, the following options configure the thread:

ConfigTypeDescriptionDefault
CONFIG_ZMK_DISPLAY_DEDICATED_THREAD_STACK_SIZEintStack size for the UI thread2048
CONFIG_ZMK_DISPLAY_DEDICATED_THREAD_PRIORITYintPriority for the UI thread5

You must also configure the driver for your display. ZMK provides the following display drivers:

Zephyr provides several display drivers as well. Search for the name of your display in Zephyr's Kconfig options documentation.

Devicetree

See the Devicetree bindings for your display. Here are the bindings for common displays:

A full list of drivers provided by Zephyr can be found in Zephyr's Devicetree bindings index.