Skip to main content

Backlight Behavior


This page contains backlight behaviors supported by ZMK.

Backlight Action Defines#

Backlight actions defines are provided through the dt-bindings/zmk/backlight.h header, which is added at the top of the keymap file:

#include <dt-bindings/zmk/backlight.h>

This will allow you to reference the actions defined in this header such as BL_TOG.

Here is a table describing the action for each define:

BL_ONTurn on backlight
BL_OFFTurn off backlight
BL_TOGToggle backlight on and off
BL_INCIncrease brightness
BL_DECDecrease brightness
BL_CYCLECycle brightness
BL_SETSet a specific brightness

Behavior Binding#

  • Reference: &bl
  • Parameter #1: The backlight action define, e.g. BL_TOG or BL_INC
  • Parameter #2: Only applies to BL_SETand is the brightness value


  1. Toggle backlight on/off

    &bl BL_TOG
  2. Sets a specific brightness

    &bl BL_SET 50

Split Keyboards#

Backlight behaviors are global: This means that when triggered, they affect both the central and peripheral side of split keyboards.