waybar-bluetooth(5) File Formats Manual waybar-bluetooth(5)

# [NAME](#NAME)

waybar - bluetooth module

# [DESCRIPTION](#DESCRIPTION)

The **bluetooth** module displays information about a bluetooth controller and its connections.

# [CONFIGURATION](#CONFIGURATION)

Addressed by **bluetooth**

**controller**:  
typeof: string  
Use the controller with the defined alias. Otherwise, a random controller is used. Recommended to define when there is more than 1 controller available to the system.

**format-device-preference**:  
typeof: array  
A ranking of bluetooth devices, addressed by their alias. The order is from **first displayed** to **last displayed**.  
If this config option is not defined or none of the devices in the list are connected, it will fall back to showing the last connected device.

**format**:  
typeof: string  
default: ** {status}**  
The format, how information should be displayed. This format is used when other formats aren't specified.

**format-disabled**:  
typeof: string  
This format is used when the displayed controller is disabled.

**format-off**:  
typeof: string  
This format is used when the displayed controller is turned off.

**format-on**:  
typeof: string  
This format is used when the displayed controller is turned on with no devices connected.

**format-connected**:  
typeof: string  
This format is used when the displayed controller is connected to at least 1 device.

**format-no-controller**:  
typeof: string  
This format is used when no bluetooth controller can be found

**format-icons**:  
typeof: array/object  
Based on the current battery percentage (see section **EXPERIMENTAL BATTERY PERCENTAGE FEATURE**), the corresponding icon gets selected.  
The order is **low** to **high**. Will only show the current battery percentage icon in the **\*-connected-battery** config options.  
Or by the state if it is an object. It will fall back to the enabled state if its derivatives are not defined (on, off, connected).

**rotate**:  
typeof: integer  
Positive value to rotate the text label (in 90 degree increments).

**max-length**:  
typeof: integer  
The maximum length in character the module should display.

**min-length**:  
typeof: integer  
The minimum length in characters the module should accept.

**align**:  
typeof: float  
The alignment of the label within the module, where 0 is left-aligned and 1 is right-aligned. If the module is rotated, it will follow the flow of the text.

**justify**:  
typeof: string  
The alignment of the text within the module's label, allowing options 'left', 'right', or 'center' to define the positioning.

**on-click**:  
typeof: string  
Command to execute when clicked on the module.

**on-click-middle**:  
typeof: string  
Command to execute when middle-clicked on the module using mousewheel.

**on-click-right**:  
typeof: string  
Command to execute when you right-click on the module.

**on-scroll-up**:  
typeof: string  
Command to execute when scrolling up on the module.

**on-scroll-down**:  
typeof: string  
Command to execute when scrolling down on the module.

**smooth-scrolling-threshold**:  
typeof: double  
Threshold to be used when scrolling.

**tooltip**:  
typeof: bool  
default: **true**  
Option to disable tooltip on hover.

**tooltip-format**:  
typeof: string  
The format, how information should be displayed in the tooltip. This format is used when other formats aren't specified.

**tooltip-format-disabled**:  
typeof: string  
This format is used when the displayed controller is disabled.

**tooltip-format-off**:  
typeof: string  
This format is used when the displayed controller is turned off.

**tooltip-format-on**:  
typeof: string  
This format is used when the displayed controller is turned on with no devices connected.

**tooltip-format-connected**:  
typeof: string  
This format is used when the displayed controller is connected to at least 1 device.

**tooltip-format-no-controller**:  
typeof: string  
This format is used when no bluetooth controller can be found

**tooltip-format-enumerate-connected**:  
typeof: string  
This format is used to define how each connected device should be displayed within 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 need 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  
Enables this module to consume all left over space dynamically.

# [FORMAT REPLACEMENTS](#FORMAT_REPLACEMENTS)

**{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}**: Show 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](#EXPERIMENTAL_BATTERY_PERCENTAGE_FEATURE)

At the time of writing, the experimental features of BlueZ need to be turned on, for the battery percentage options listed below to work.

## [FORMAT REPLACEMENT](#FORMAT_REPLACEMENT)

**{device\_battery\_percentage}**: Battery percentage of the displayed device if available. Use only in the config options defined below.

## [CONFIGURATION](#CONFIGURATION~2)

**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  
This format is used to define how each connected device with a battery should be displayed within the **device\_enumerate** format replacement option.  
When this config option is not defined, it will fall back on the **tooltip-format-enumerate-connected** config option.

# [EXAMPLES](#EXAMPLES)

```
"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}"
}
```

```
"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](#STYLE)

- **#bluetooth**
- **#bluetooth.disabled**
- **#bluetooth.off**
- **#bluetooth.on**
- **#bluetooth.connected**
- **#bluetooth.discoverable**
- **#bluetooth.discovering**
- **#bluetooth.pairable**

2026-10-16

---

Document: waybar-bluetooth(5) from waybar 0.15.0-r0 (Chainguard OS)