waybar-bluetooth(5)

✨ waybar-bluetooth(5) ✨

okay bestie, welcome to the waybar bluetooth module page 🌸 this is a section 5 (File Formats Manual) situation, so grab a strawberry drink and let's get into it 🍓

💙 NAME 💙

waybar — bluetooth module. that's it, that's the name, slay.

🦋 DESCRIPTION 🦋

The bluetooth module shows you info about a bluetooth controller and all its connections. it's giving "who's connected to me right now" and honestly? iconic. ✨

---

🎀 CONFIGURATION 🎀

This block is addressed by bluetooth, so that's the key you're vibing with in your config 🫶

• controller — typeof: string — use the controller that has the alias you specify. If you don't, a random controller gets picked (chaotic of waybar honestly). Recommended to define this whenever there's more than 1 controller available on your system.
• format-device-preference — typeof: array — a ranking of bluetooth devices, addressed by their alias. order goes from first displayed to last displayed 💅 if this option isn't defined, or none of the devices in the list are connected, it falls back to showing the last connected device.
• format — typeof: string — default: {status} — the format for how info should be displayed. this one is used when the other formats aren't specified.
• format-disabled — typeof: string — used when the displayed controller is disabled.
• format-off — typeof: string — used when the displayed controller is turned off.
• format-on — typeof: string — used when the displayed controller is turned on with no devices connected.
• format-connected — typeof: string — used when the displayed controller is connected to at least 1 device.
• format-no-controller — typeof: string — used when no bluetooth controller can be found.
• format-icons — typeof: array/object — based on the current battery percentage (peep the EXPERIMENTAL BATTERY PERCENTAGE FEATURE section below), the matching icon gets selected. order goes low to high. it'll only show the current battery percentage icon inside the *-connected-battery config options. or it goes by state if it's an object — and it falls back to the enabled state if its derivatives aren't defined (on, off, connected).
• rotate — typeof: integer — positive value rotates the text label (in 90 degree increments).
• max-length — typeof: integer — the max length, in characters, that the module should display.
• min-length — typeof: integer — the min length, in characters, that the module should accept.
• align — typeof: float — the alignment of the label inside the module, where 0 is left-aligned and 1 is right-aligned. if the module is rotated, it follows the flow of the text, periodt.
• justify — typeof: string — the alignment of the text inside the module's label; 'left', 'right' or 'center' define the positioning.
• on-click — typeof: string — command to execute when you click the module.
• on-click-middle — typeof: string — command to execute when you middle-click the module using the mousewheel.
• on-click-right — typeof: string — command to execute when you right-click the module.
• on-scroll-up — typeof: string — command to execute when you scroll up on the module.
• on-scroll-down — typeof: string — command to execute when you scroll down on the module.
• smooth-scrolling-threshold — typeof: double — threshold used when scrolling.
• tooltip — typeof: bool — default: true — option to disable the tooltip on hover.
• tooltip-format — typeof: string — the format for how info should be displayed in the tooltip. this one is used when the other formats aren't specified.
• tooltip-format-disabled — typeof: string — used when the displayed controller is disabled.
• tooltip-format-off — typeof: string — used when the displayed controller is turned off.
• tooltip-format-on — typeof: string — used when the displayed controller is turned on with no devices connected.
• tooltip-format-connected — typeof: string — used when the displayed controller is connected to at least 1 device.
• tooltip-format-no-controller — typeof: string — used when no bluetooth controller can be found.
• tooltip-format-enumerate-connected — typeof: string — defines how each connected device should be displayed inside the device_enumerate format replacement in the tooltip menu.
• menu — typeof: string — action that popups the menu.
• menu-file — typeof: string — location of the menu descriptor file. there needs to be an element of type GtkMenu with id menu.
• menu-actions — typeof: array — the actions corresponding to the buttons of the menu.
• expand — typeof: bool — default: false — lets this module consume all the left over space dynamically. main character energy fr 💅

---

🧚 FORMAT REPLACEMENTS 🧚

these are the little magic words you drop in your formats ✨

• {status} — status of the bluetooth device.
• {icon} — icon, as defined in format-icons.
• {num_connections} — number of connections the displayed controller has.
• {controller_address} — address of the displayed controller.
• {controller_address_type} — address type of the displayed controller.
• {controller_alias} — alias of the displayed controller.
• {device_address} — address of the displayed device.
• {device_address_type} — address type of the displayed device.
• {device_alias} — alias of the displayed device.
• {device_enumerate} — shows a list of all connected devices, each on a separate line. define the format of each device with the tooltip-format-enumerate-connected and/or tooltip-format-enumerate-connected-battery config options. can only be used in the tooltip-related format options.

---

🔬 EXPERIMENTAL BATTERY PERCENTAGE FEATURE 🔬

as of the time of writing, the experimental features of BlueZ need to be turned on for the battery percentage options listed below to work. no cap, you gotta enable those first 🫶

💖 FORMAT REPLACEMENT 💖

• {device_battery_percentage} — battery percentage of the displayed device, if available. use it only in the config options defined below.

💖 CONFIGURATION 💖

• format-connected-battery — typeof: string — this format is used when the displayed device provides its battery percentage.
• tooltip-format-connected-battery — typeof: string — this format is used when the displayed device provides its battery percentage.
• tooltip-format-enumerate-connected-battery — typeof: string — defines how each connected device with a battery should be displayed inside the device_enumerate format replacement option. when this config option isn't defined, it falls back on the tooltip-format-enumerate-connected config option.

---

🌈 EXAMPLES 🌈

first one, the classic ✨

"bluetooth": {
     // "controller": "controller1", // specify the alias of the controller if there are more than 1 on the system
     "format": " {status}",
     "format-disabled": "", // an empty format will hide the module
     "format-connected": " {num_connections} connected",
     "tooltip-format": "{controller_alias}\t{controller_address}",
     "tooltip-format-connected": "{controller_alias}\t{controller_address}\n\n{device_enumerate}",
     "tooltip-format-enumerate-connected": "{device_alias}\t{device_address}"
}

and the second one, battery edition 😌

"bluetooth": {
     "format": " {status}",
     "format-connected": " {device_alias}",
     "format-connected-battery": " {device_alias} {device_battery_percentage}%",
     // "format-device-preference": [ "device1", "device2" ], // preference list deciding the displayed device
     "tooltip-format": "{controller_alias}\t{controller_address}\n\n{num_connections} connected",
     "tooltip-format-connected": "{controller_alias}\t{controller_address}\n\n{num_connections} connected\n\n{device_enumerate}",
     "tooltip-format-enumerate-connected": "{device_alias}\t{device_address}",
     "tooltip-format-enumerate-connected-battery": "{device_alias}\t{device_address}\t{device_battery_percentage}%"
}

---

💅 STYLE 💅

these are the CSS selectors you get to dress up, go off 👑

• #bluetooth
• #bluetooth.disabled
• #bluetooth.off
• #bluetooth.on
• #bluetooth.connected
• #bluetooth.discoverable
• #bluetooth.discovering
• #bluetooth.pairable

---

aaaand that's the whole page bestie, 10/10 module, no notes 💖 this was waybar-bluetooth(5), dated 2026-02-08 — go forth and pair some devices 🦋✨