Keyboard Backlight OSD for Hyprland with SwayOSD

Add beautiful on-screen display (OSD) popups for keyboard backlight control on Hyprland, matching the style of volume/brightness controls.

Features

Clean progress bar OSD matching system brightness/volume style
Consistent 10% increment steps (0%, 10%, 20%...100%)
Works with fn+F3/F4 keys on Apple Silicon (Asahi Linux)
Uses SwayOSD for unified look

Requirements

Hyprland window manager
SwayOSD (swayosd-client)
brightnessctl
jq

Installation

1. Create the keyboard backlight control script

Create ~/.config/hypr/kbd-backlight-osd.sh:

#!/bin/bash

# Script to control keyboard backlight with swayosd OSD display
# Usage: kbd-backlight-osd.sh [raise|lower]

DEVICE="kbd_backlight"
STEP=10  # Percentage step

# Get current monitor for OSD display
MONITOR=$(hyprctl monitors -j | jq -r '.[] | select(.focused == true).name')

# Get max brightness value
MAX=$(brightnessctl --device="$DEVICE" max)

# Calculate step size in raw value (10% of max)
RAW_STEP=$((MAX * STEP / 100))

# Get current brightness before adjustment
CURRENT=$(brightnessctl --device="$DEVICE" get)

# Special handling for going to 0%
if [ "$1" = "lower" ] && [ $CURRENT -le $RAW_STEP ]; then
    # Set to 0 first
    brightnessctl --device="$DEVICE" set 0 > /dev/null
    # Use swayosd with minimal progress value
    swayosd-client \
        --monitor "$MONITOR" \
        --custom-icon "keyboard-brightness-symbolic" \
        --custom-progress "0.00000000000000000000000001" \
        --custom-progress-text "0%"
    exit 0
fi

# Calculate new value and display percentage based on action
case "$1" in
    raise)
        # Calculate new value and ensure it's aligned to 10% increments
        NEW=$((CURRENT + RAW_STEP))
        # If we're close to max (within one step), go to max
        if [ $NEW -ge $((MAX - RAW_STEP)) ]; then
            NEW=$MAX
        else
            # Otherwise round to nearest 10% increment
            NEW=$((((NEW + RAW_STEP/2) / RAW_STEP) * RAW_STEP))
        fi
        ;;
    lower)
        # Calculate new value and ensure it's aligned to 10% increments
        NEW=$((CURRENT - RAW_STEP))
        # Round to nearest 10% increment
        NEW=$((((NEW + RAW_STEP/2) / RAW_STEP) * RAW_STEP))
        # Don't go below 0
        if [ $NEW -lt 0 ]; then NEW=0; fi
        ;;
    *)
        echo "Usage: $0 [raise|lower]"
        exit 1
        ;;
esac

# Set the new brightness
brightnessctl --device="$DEVICE" set "$NEW" > /dev/null

# Calculate percentage to display
PERCENTAGE=$(((NEW * 100 / MAX + 5) / 10 * 10))

# Calculate progress value for swayosd (0.0 to 1.0)
PROGRESS=$(awk "BEGIN {printf \"%.2f\", $NEW / $MAX}")

# Display OSD using swayosd
swayosd-client \
    --monitor "$MONITOR" \
    --custom-icon "keyboard-brightness-symbolic" \
    --custom-progress "$PROGRESS" \
    --custom-progress-text "${PERCENTAGE}%"

2. Make the script executable

chmod +x ~/.config/hypr/kbd-backlight-osd.sh

3. Add key bindings to Hyprland

Add to your ~/.config/hypr/bindings.conf or hyprland.conf:

# Keyboard backlight controls (fn+F3 and fn+F4) with swayosd
bindeld = , XF86LaunchA, Keyboard brightness down, exec, ~/.config/hypr/kbd-backlight-osd.sh lower
bindeld = , XF86Search, Keyboard brightness up, exec, ~/.config/hypr/kbd-backlight-osd.sh raise

Note: The key codes XF86LaunchA and XF86Search are specific to Apple Silicon keyboards. For other keyboards, you may need different key codes.

4. Reload Hyprland configuration

hyprctl reload

Customization

Adjust increment percentage

Change the STEP variable in the script (default is 10):

STEP=5  # For 5% increments

Change the icon

Modify the --custom-icon parameter. Available icons follow the Freedesktop Icon Naming Specification.

Different keyboard device

If your keyboard backlight has a different device name, find it with:

ls /sys/class/leds/ | grep -i kbd

Then update the DEVICE variable in the script.

Troubleshooting

OSD not appearing

Ensure SwayOSD server is running: systemctl --user status swayosd
Check if the device exists: brightnessctl --device='kbd_backlight' get

Wrong key codes

Find your key codes with:

wev  # Press your keyboard backlight keys and note the key names

Permission issues

If you get permission errors, you may need to add your user to the video or input group:

sudo usermod -a -G video,input $USER

Then log out and back in.

Credits

Created for Omarchy Arch setup on Asahi Linux (Apple Silicon) with Hyprland and SwayOSD.

License

Public Domain - Feel free to use and modify as needed.

jondkinney/README.md