i3status-rs(1)

📦

version 0.36.2 · 2 versions

0.36.2 · arch rolling, nixpkgs unstable (latest)
0.36.1 · nixos 26.05

💖 i3status-rs(1) — General Commands Manual, bestie edition ✨

✨ NAME ✨

i3status-rs — a feature-rich and resource-friendly replacement for i3status, written in Rust. 💅

💅 SYNOPSIS 💅

i3status-rs [--never-pause] [-j|--threads] [-h|--help] [-V|--version]
[CONFIG]

🌈 DESCRIPTION 🌈

Okay so i3status-rs is literally a feature-rich and resource-friendly replacement for i3status(1), written in Rust. ✨ The i3status-rs program writes a stream of configurable "blocks" of system information (time, battery status, volume, etc.) to standard output in the JSON format understood by i3bar(1) and sway-bar(5). That's the whole vibe. 🫶

🎀 OPTIONS 🎀

--never-pause — Ignore any attempts by i3 to pause the bar when hidden/fullscreen. 🙈
-j, --threads=BLOCKING_THREADS [default: 2] — The maximum number of blocking threads spawned by tokio. 🧵
-h, --help — Print help (see a summary with '-h'). 🆘
-V, --version — Print version. 👑
[CONFIG] [default: config.toml] — Sets a TOML config file. 📝
1. If full absolute path given, then use it as is: /home/foo/i3rs-config.toml
2. If filename given, e.g. "custom_theme.toml", then first look in $XDG_CONFIG_HOME/i3status-rust
3. Then look for it in $XDG_DATA_HOME/i3status-rust
4. Otherwise look for it in /usr/share/i3status-rust

🧚 BLOCKS 🧚

Each block is its own little main character. 👑

🔥 amd_gpu 🔥

Display the stats of your AMD GPU. 💜

🎀 Configuration 🎀

device — The device in /sys/class/drm/ to read from. Default: Any AMD card.
format — A [MultiFormat][MaybeMultiFormatConfig] string to customise the output of this block. See below for available placeholders. Default: [" $icon $utilization "].
interval — Update interval in seconds. Default: 5.

Placeholders:

icon — A static icon. Type: Icon; Unit: -.
utilization — GPU utilization. Type: Number; Unit: %.
vram_total — Total VRAM. Type: Number; Unit: Bytes.
vram_used — Used VRAM. Type: Number; Unit: Bytes.
vram_used_percents — Used VRAM / Total VRAM. Type: Number; Unit: %.

Actions:

toggle_format — Toggles between format and format_alt. Default button: -.
DEPRECATED
next_format — Switches to the next format in the list. Default button: Left.
prev_format — Switches to the previous format in the list. Default button: Right.

🌟 Example 🌟

[[block]]
block = "amd_gpu"
format = " $icon $utilization "
format_alt = " $icon MEM: $vram_used_percents ($vram_used/$vram_total) "
interval = 1

🦋 Icons Used 🦋

gpu ($icon)

🌙 backlight 🌙

The brightness of a backlight device. ✨

This block reads brightness information directly from the filesystem, so it works under both X11 and Wayland. 🖥️ The block uses inotify to listen for changes in the device’s brightness directly, so there is no need to set an update interval. ⏱️ This block uses DBus to set brightness level using the mouse wheel, but will fallback to sysfs if systemd-logind is not used. 🖱️

📐 Root scaling 📐

Some devices expose raw values that are best handled with nonlinear scaling. The human perception of lightness is close to the cube root of relative luminance, so settings for root_scaling between 2.4 and 3.0 are worth trying. For devices with few discrete steps this should be 1.0 (linear). More information: https://en.wikipedia.org/wiki/Lightness 💡

🎀 Configuration 🎀

device — A regex to match against /sys/class/backlight devices to read brightness information from (can match 1 or more devices). When there is no device specified, this block will display information for all devices found in the /sys/class/backlight directory. Default: Default device.
format — A string to customise the output of this block. See below for available placeholders. Default: " $icon $brightness ".
missing_format — A string to customise the output of this block. No placeholders available. Default: " no backlight devices ".
step_width — The brightness increment to use when scrolling, in percent. Default: 5.
minimum — The minimum brightness that can be scrolled down to. Default: 5.
maximum — The maximum brightness that can be scrolled up to. Default: 100.
cycle — The brightnesses to cycle through on each click. Default: [minimum, maximum].
root_scaling — Scaling exponent reciprocal (ie. root). Default: 1.0.
invert_icons — Invert icons’ ordering, useful if you have colorful emoji. Default: false.
ddcci_sleep_multiplier — See ddcutil documentation ⟨https://www.ddcutil.com/performance_options/#option-sleep-multiplier⟩. Default: 1.0.
ddcci_max_tries_write_read — The maximum number of times to attempt writing to or reading from a ddcci monitor. Default: 10.

Placeholders:

icon — Icon based on backlight’s state. Type: Icon; Unit: -.
brightness — Current brightness. Type: Number; Unit: %.

Actions:

cycle — Default button: Left.
brightness_up — Default button: Wheel Up.
brightness_down — Default button: Wheel Down.

🌟 Example 🌟

[[block]]
block = "backlight"
device = "intel_backlight"

Hide missing backlight:

[[block]]
block = "backlight"
missing_format = ""

🧚 calibright 🧚

Additional display brightness calibration can be set in $XDG_CONFIG_HOME/calibright/config.toml. See https://github.com/bim9262/calibright for more details. This block will override any global config set in $XDG_CONFIG_HOME/calibright/config.toml. 💅

💀 D-Bus Fallback 💀

If you don’t use systemd-logind, i3status-rust will attempt to set the brightness using sysfs. In order to do this you’ll need to have write permission. You can do this by writing a udev rule for your system.

First, check that your user is a member of the “video” group using the groups command. Then add a rule in the /etc/udev/rules.d/ directory containing the following, for example in backlight.rules:

ACTION=="add", SUBSYSTEM=="backlight", GROUP="video", MODE="0664"

This will allow the video group to modify all backlight devices. You will also need to restart for this rule to take effect. 🔁

🦋 Icons Used 🦋

backlight ($icon, as a progression)

🔋 battery 🔋

Information about the internal power supply. ⚡

This block can display the current battery state (Full, Charging or Discharging), percentage charged and estimate time until (dis)charged for an internal power supply. 🪫🔋

⚙️ Configuration ⚙️

okay bestie here's the battery config table, every key, no skips 💅

device — for sysfs/UPower: the device in /sys/class/power_supply/ to read from. (You can also put "DisplayDevice" for UPower — that's a single logical power source that represents all the physical power sources. Super handy if your system has multiple batteries, because then DisplayDevice acts like you've got one big chonky battery instead of a whole squad.) For apc_ups: IPv4Address:port or hostname:port. Default: for sysfs, the first battery device found in /sys/class/power_supply, with "BATx" or "CMBx" entries taking precedence; for apc_ups, "localhost:3551"; for upower, DisplayDevice.
driver — one of "sysfs", "apc_ups", or "upower". Default: "sysfs".
model — if present, the contents of /sys/class/power_supply/.../model_name must match this value. Typical use is to select by model name on devices that change their path (iconic for flaky hardware fr). Default: N/A.
interval — update interval, in seconds. Only relevant for driver = "sysfs" or "apc_ups". Default: 10.
format — a string to customise the output of this block ✨ see below for available placeholders. Default: " $icon $percentage ".
full_format — same as format but for when the battery is full. Default: " $icon ".
charging_format — same as format but for when the battery is charging. Default: links to format 🔗.
empty_format — same as format but for when the battery is empty. Default: " $icon ".
not_charging_format — same as format but for when the battery is not charging. Defaults to the full battery icon, because so many batteries report this status when they're actually full 🙄 (they're lying but okay). Default: " $icon ".
missing_format — same as format if the battery cannot be found. Default: " $icon ".
info — minimum battery level where state is set to info. Default: 60.
good — minimum battery level where state is set to good. Default: 60.
warning — minimum battery level where state is set to warning. Default: 30.
critical — minimum battery level where state is set to critical. Default: 15.
full_threshold — percentage above which the battery is considered full (full_format shown). Default: 95.
empty_threshold — percentage below which the battery is considered empty. Default: 7.5.

the placeholders, bestie 🔋

icon — icon based on battery's state. Type: Icon. Unit: -.
percentage — battery level, in percent. Type: Number. Unit: Percents.
time_remaining — time remaining until (dis)charge is complete. Only presented if the battery's status is (dis)charging. Type: Duration. Unit: -.
time — time remaining until (dis)charge is complete. Only presented if the battery's status is (dis)charging. Type: String. Unit: -. DEPRECATED 💀
power — power consumption by the battery, or from the power supply when charging. Type: String or Float. Unit: Watts.

time has been deprecated in favor of time_remaining. use the new one, she ate and left no crumbs 🫶

Examples 🌸

basic usage, the classic:

[[block]]
block = "battery"
format = " $icon $percentage "

[[block]]
block = "battery"
format = " $percentage {$time_remaining.dur(hms:true, min_unit:m) |}"
device = "DisplayDevice"
driver = "upower"

hiding a missing battery (iconic, no notes):

[[block]]
block = "battery"
missing_format = ""

Icons Used 🎀

bat — used as $icon in format, full_format, empty_format, not_charging_format, as a progression.
bat_charging — used as $icon in charging_format, as a progression.
bat_not_available — used as $icon in missing_format.

🔵 bluetooth 🔵

monitor a Bluetooth device 💙

this block displays the connectivity of a given Bluetooth device, plus the battery level if that's supported. It relies on the Bluez D-Bus API.

when the device can be identified as an audio headset, a keyboard, a joystick, or a mouse, it uses the relevant icon (we love a device that knows what it is 💅). otherwise it falls back on the generic Bluetooth symbol.

right-clicking the block will attempt to connect (or disconnect) the device. so convenient, no cap.

Note: battery level information is not reported for some devices. enabling experimental features of bluez may fix it. (blame the device, not the block 🙈)

⚙️ Configuration ⚙️

mac — MAC address of the Bluetooth device. Default: Required (yes bestie, mandatory, no skipping).
adapter_mac — MAC Address of the Bluetooth adapter (in case your device was connected to multiple currently available adapters). Default: None.
format — a string to customise the output of this block. See below for available placeholders. Default: " $icon $name{ $percentage|} ".
disconnected_format — a string to customise the output of this block. See below for available placeholders. Default: " $icon{ $name|} ".
battery_state — a mapping from battery percentage to the block's state (color). See example below. Default: 0..15 -> critical, 16..30 -> warning, 31..60 -> info, 61..100 -> good.

the placeholders 🦋

icon — icon based on what type of device is connected. Type: Icon. Unit: -.
name — device's name. Type: Text. Unit: -.
percentage — device's battery level (may be absent if the device is not supported). Type: Number. Unit: %.
battery_icon — battery icon (may be absent if the device is not supported). Type: Icon. Unit: -.
available — present if the device is available. Type: Flag. Unit: -.

actions 🖱️

toggle — default button: Right.

Examples ✨

this example just shows the icon when the device is connected:

[[block]]
block = "bluetooth"
mac = "00:18:09:92:1B:BA"
disconnected_format = ""
format = " $icon "
[block.battery_state]
"0..20" = "critical"
"21..70" = "warning"
"71..100" = "good"

Icons Used 👑

headphones — used as $icon for bluetooth devices identifying as "audio-card", "audio-headset" or "audio-headphones".
joystick — used as $icon for bluetooth devices identifying as "input-gaming".
keyboard — used as $icon for bluetooth devices identifying as "input-keyboard".
mouse — used as $icon for bluetooth devices identifying as "input-mouse".
bluetooth — used as $icon for all other devices, and when the device is unavailable.
bat — used as $battery_icon, as a progression, for devices reporting a battery level.

📅 calendar 📅

calendar 🗓️

this block displays upcoming calendar events retrieved from a CalDav ICalendar server.

okay so here's the rest of the knobs for this block — key, what it does, and what it defaults to 🎀

next_event_format — a string that customises what this block shows when there's a next event in the calendar. Peep the placeholders list below for what you can slot in. Default:

 " $icon $start.datetime(f:`%a %H:%M') $summary "

ongoing_event_format — a string that customises the output when an event is currently ongoing. Default:

 " $icon $summary (ends at $end.datetime(f:`%H:%M')) "

no_events_format — a string that customises the output when there are no events at all. Default: " $icon "
redirect_format — a string that customises the output when authorization is being asked for. Default: " $icon Check your web browser "
fetch_interval — how often to fetch events, in seconds. Default: 60
alternate_events_interval — interval in seconds for alternating between overlapping events. Default: 10
events_within_hours — how many hours into the future to look for events. Default: 48
source — array of sources to pull calendars from. Default: []
warning_threshold — warning threshold in seconds for the upcoming event. Default: 300
browser_cmd — command used to open event details in a browser. The block passes the HTML link as an argument. Default: "xdg-open"

✨ Source Configuration ✨

url — the CalDav calendar server URL. Default: N/A
auth — authentication configuration, one of unauthenticated, basic, or oauth2. Default: unauthenticated
calendars — a list of calendar names to monitor. If it's empty, all calendars will be fetched. Default: []

⚠️ note bestie: currently only one source is supported. one. singular. 💀

And here's the action it can do:

open_link — opens the HTML link of the event. Default button: Left

🦋 Examples 🦋

Unauthenticated 🌸

[[block]]
block = "calendar"
next_event_format = " $icon $start.datetime(f:'%a %H:%M') $summary "
ongoing_event_format = " $icon $summary (ends at $end.datetime(f:'%H:%M')) "
no_events_format = " $icon no events "
fetch_interval = 30
alternate_events_interval = 10
events_within_hours = 48
warning_threshold = 600
browser_cmd = "firefox"
[[block.source]]
url = "https://caldav.example.com/calendar/"
calendars = ["user/calendar"]
[block.source.auth]
type = "unauthenticated"

Basic Authentication 🔐

[[block]]
block = "calendar"
next_event_format = " $icon $start.datetime(f:'%a %H:%M') $summary "
ongoing_event_format = " $icon $summary (ends at $end.datetime(f:'%H:%M')) "
no_events_format = " $icon no events "
fetch_interval = 30
alternate_events_interval = 10
events_within_hours = 48
warning_threshold = 600
browser_cmd = "firefox"
[[block.source]]
url = "https://caldav.example.com/calendar/"
calendars = [ "Holidays" ]
[block.source.auth]
type = "basic"
username = "your_username"
password = "your_password"

💡 Note: you can also put the username and password in a separate TOML file.

~/.config/i3status-rust/example_credentials.toml

username = "my-username"
password = "my-password"

Source auth configuration with credentials_path:

[block.source.auth]
type = "basic"
credentials_path = "~/.config/i3status-rust/example_credentials.toml"

OAuth2 Authentication (Google Calendar) 👑

To hit Google's CalDav API you gotta follow these steps to enable the API and grab your client_id and client_secret:

Go to the Google Cloud Console: navigate to the Google Cloud Console.
Create a New Project: if you don't already have a project, click on the project dropdown and select "New Project". Give your project a name and click "Create".
Enable the CalDAV API: in the project dashboard, go to the "APIs & Services" > "Library". Search for "CalDAV API" and click on it, then click "Enable".
Set Up OAuth Consent Screen: go to "APIs & Services" > "OAuth consent screen". Fill out the required information and save.
Create Credentials:
- Navigate to "APIs & Services" > "Credentials".
- Click "Create Credentials" and select "OAuth 2.0 Client IDs".
- Configure the consent screen if you haven't already.
- Set the application type to "Web application".
- Add your authorized redirect URIs. For example, http://localhost:8080.
- Click "Create" and note down the client_id and client_secret.
Download the Credentials: click on the download icon next to your OAuth 2.0 Client ID to download the JSON file containing your client ID and client secret. Use these values in your configuration.

[[block]]
block = "calendar"
next_event_format = " $icon $start.datetime(f:'%a %H:%M') $summary "
ongoing_event_format = " $icon $summary (ends at $end.datetime(f:'%H:%M')) "
no_events_format = " $icon no events "
fetch_interval = 30
alternate_events_interval = 10
events_within_hours = 48
warning_threshold = 600
browser_cmd = "firefox"
[[block.source]]
url = "https://apidata.googleusercontent.com/caldav/v2/"
calendars = ["primary"]
[block.source.auth]
type = "oauth2"
client_id = "your_client_id"
client_secret = "your_client_secret"
auth_url = "https://accounts.google.com/o/oauth2/auth"
token_url = "https://oauth2.googleapis.com/token"
auth_token = "~/.config/i3status-rust/calendar.auth_token"
redirect_port = 8080
scopes = ["https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/calendar.events"]

💡 Note: you can also put client_id and client_secret in a separate TOML file.

~/.config/i3status-rust/google_credentials.toml

client_id = "my-client_id"
client_secret = "my-client_secret"

Source auth configuration with credentials_path:

[block.source.auth]
type = "oauth2"
credentials_path = "~/.config/i3status-rust/google_credentials.toml"
auth_url = "https://accounts.google.com/o/oauth2/auth"
token_url = "https://oauth2.googleapis.com/token"
auth_token = "~/.config/i3status-rust/calendar.auth_token"
redirect_port = 8080
scopes = ["https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/calendar.events"]

🎀 Format Configuration 🎀

The format configuration is just a string that can include placeholders, and those placeholders get swapped out for dynamic content. The placeholders are:

$summary — summary of the event
$description — description of the event
$url — url of the event
$location — location of the event
$start — start time of the event
$end — end time of the event

⭐ Icons Used ⭐

calendar ($icon)

💻 cpu 💻

literally CPU statistics, that's the whole vibe ✨

Configuration

format — a [MultiFormat][MaybeMultiFormatConfig] string to customise the output of this block. See the placeholders below for what you can use. Default: [" $icon $utilization "]
interval — update interval in seconds. Default: 5
info_cpu — percentage of CPU usage where the state gets set to info. Default: 30.0
warning_cpu — percentage of CPU usage where the state gets set to warning. Default: 60.0
critical_cpu — percentage of CPU usage where the state gets set to critical. Default: 90.0

Now the placeholders, with their type and unit so you know what you're working with:

icon — an icon. Type: Icon, Unit: -
utilization — average CPU utilization. Type: Number, Unit: %
utilization<N> — utilization of the Nth logical CPU. Type: Number, Unit: %
barchart — utilization of all logical CPUs, presented as a barchart. Type: Text, Unit: -
frequency — average CPU frequency (may be absent if the CPU isn't supported). Type: Number, Unit: Hz
frequency<N> — frequency of the Nth logical CPU (may be absent if the CPU isn't supported). Type: Number, Unit: Hz
max_frequency — max frequency of all logical CPUs. Type: Number, Unit: Hz
boost — CPU turbo boost status (may be absent if the CPU isn't supported). Type: Text, Unit: -
toggle_format — flips your block between format and format_alt 💅 — default button: -
next_format — DEPRECATED — moves on to the next format in the list — default button: Left
prev_format — DEPRECATED — hops back to the previous format in the list — default button: Right

🌸 Example

[[block]]
block = "cpu"
interval = 1
format = " $icon $barchart $utilization "
format_alt = " $icon $frequency{ $boost|} "
info_cpu = 20
warning_cpu = 50
critical_cpu = 90

🎀 Icons Used

cpu ($icon, as a progression) ✨
cpu_boost_on ($boost) 🔥
cpu_boost_off ($boost) 💀

🦋 custom

Lowkey the most iconic block ever: it just shows the output of a custom shell command you give it. main character energy honestly.

For further customisation, use the json option and have the shell command output valid JSON in the schema below:

{"icon": "...", "state": "...", "text": "...", "short_text": "..."}

icon is optional (default ““), state is optional, it may be Idle, Info, Good, Warning, Critical (default Idle), and short_text is optional. 🫶

💖 Configuration

format — A string to customise the output of this block. See below for available placeholders. Default: "{ $icon|} $text.pango-str() "
command — Shell command to execute & display. Default: None
persistent — Run command in the background; update display for each output line of the command. Default: false
cycle — Commands to execute and change when the button is clicked. Default: None
interval — Update interval in seconds (or "once" to update only once). Default: 10
json — Use JSON from command output to format the block. If the JSON is not valid, the block will error out. Default: false
watch_files — Watch files to trigger update on file modification. Supports path expansions e.g. ~. Default: None
hide_when_empty — Hides the block when the command output (or json text field) is empty. Default: false
shell — Specify the shell to use when running commands. Default: $SHELL if set, otherwise fallback to sh

✨ Placeholders

icon — Value of icon field from JSON output when it’s non-empty — type: Icon — unit: -
text — Output of the script or text field from JSON output — type: Text
short_text — short_text field from JSON output — type: Text

🎀 Actions

cycle — default button: Left

🍓 Examples

Display temperature, update every 10 seconds:

[[block]]
block = "custom"
command = ''' cat /sys/class/thermal/thermal_zone0/temp | awk '{printf("%.1f\n",$1/1000)}' '''

Cycle between “ON” and “OFF”, update every 1 second, run next cycle command when block is clicked:

[[block]]
block = "custom"
cycle = ["echo ON", "echo OFF"]
interval = 1
[[block.click]]
button = "left"
action = "cycle"

Use JSON output:

[[block]]
block = "custom"
command = "echo '{\"icon\":\"weather_thunder\",\"state\":\"Critical\", \"text\": \"Danger!\"}'"
json = true

Display kernel, update the block only once:

[[block]]
block = "custom"
command = "uname -r"
interval = "once"

Display the screen brightness on an intel machine and update this only when pkill -SIGRTMIN+4 i3status-rs is called:

[[block]]
block = "custom"
command = ''' cat /sys/class/backlight/intel_backlight/brightness | awk '{print $1}' '''
signal = 4
interval = "once"

Update block when one or more specified files are modified:

[[block]]
block = "custom"
command = "cat custom_status"
watch_files = ["custom_status"]
interval = "once"

🙈 TODO:

Use shellexpand

🌈 custom_dbus

A block controlled by the DBus 💅 — yes bestie, you are in charge now.

This block creates a new DBus object in rs.i3status service. This object implements rs.i3status.custom interface which allows you to set block’s icon, text and state.

Output of busctl --user introspect rs.i3status /<path> rs.i3status.custom:

NAME                                TYPE      SIGNATURE RESULT/VALUE FLAGS
rs.i3status.custom                  interface -         -            -
.SetIcon                            method    s         s            -
.SetState                           method    s         s            -
.SetText                            method    ss        s            -

💜 Configuration

format — A string to customise the output of this block. Default: "{ $icon|}{ $text.pango-str()|} "

⭐ Placeholders

icon — Value of icon set via SetIcon if the value is non-empty string. — type: Icon — unit: -
text — Value of the first string from SetText — type: Text
short_text — Value of the second string from SetText — type: Text

🧚 Example

Config:

[[block]]
block = "custom_dbus"
path = "/my_path"

Usage:

# set full text to 'hello' and short text to 'hi'
busctl --user call rs.i3status /my_path rs.i3status.custom SetText ss hello hi
# set icon to 'music'
busctl --user call rs.i3status /my_path rs.i3status.custom SetIcon s music
# set state to 'good'
busctl --user call rs.i3status /my_path rs.i3status.custom SetState s good

Okay so real talk: because it’s impossible to publish objects to the same name from different processes, having multiple dbus blocks in different bars won’t work. 😭 As a workaround, you can set the env var I3RS_DBUS_NAME to set the interface a bar works on to differentiate between different processes. For example, setting this to top, will allow you to use rs.i3status.top.

🙈 TODO

Send a signal on click?

🔥 disk_iostats

Disk I/O statistics — watching your drives go brrrr in real time. 💀

💖 Configuration

device — Block device or partition name to monitor (as specified in /dev/). Default: If not set, device will be automatically selected every interval
format — A string to customise the output of this block. See below for available placeholders. Default: " $icon $speed_read.eng(prefix:K) $speed_write.eng(prefix:K) "
interval — Update interval in seconds. Default: 2
missing_format — Same as format but for when the device is missing. Default: " × "

✨ Placeholders

icon — A static icon — type: Icon — unit: -
device — The name of device — type: Text — unit: -
speed_read — Read speed — type: Number — unit: Bytes per second
speed_write — Write speed — type: Number — unit: Bytes per second

🎀 Examples

[[block]]
block = "disk_iostats"
device = "sda"
format = " $icon $speed_write.eng(prefix:K) "

Use labeled Games partition via persistent device names from /dev/disk/by-*/ 👑

[[block]]
block = "disk_iostats"
device = "disk/by-partlabel/Games"
format = " $icon $speed_write.eng(prefix:K) "

🦋 Icons Used

disk_drive ($icon) 🫶

🌸 disk_space

Disk usage statistics

✨ Configuration ✨

Okay bestie, here's everything you can tweak 👇

path — the path it collects info from. Path expansions are a thing, e.g. ~. Default: "/" 🗂️
interval — update time, in seconds. Default: 20
format — a [MultiFormat][MaybeMultiFormatConfig] string to customise the block's output. Peep the placeholders below. Default: [" $icon $available "]
warning — the value that flips the block into warning state. Default: 20.0 ⚠️
alert — the value that flips the block into critical state. Default: 10.0 🚨
info_type — picks which info actually affects the block state. Possible values: "available", "free" and "used". Default: "available"
alert_unit — the unit used by the alert and warning options. If you don't set it, percents are used. Possible values: "B", "kB", "KB", "KiB", "MB", "MiB", "GB", "Gib", "TB" and "TiB". Default: None
backend — the backend used when querying disk usage. Possible values: "vfs" (like du(1)) and "btrfs". Default: "vfs"

And here's your placeholder menu 🍓

icon — a static icon. Icon, unit: -
path — whatever the path option is set to. Text, unit: -
percentage — free or used percentage, depends on info_type. Number, unit: %
total — total disk space. Number, unit: Bytes
used — used disk space. Number, unit: Bytes
free — free disk space. Number, unit: Bytes
available — available disk space (that's free disk space minus the reserved system space). Number, unit: Bytes

Actions you can click, no cap 🖱️

toggle_format — toggles between format and format_alt. Default button: -. DEPRECATED 💀
next_format — switches to the next format in the list. Default button: Left
prev_format — switches to the previous format in the list. Default button: Right

🌸 Examples 🌸

[[block]]
block = "disk_space"
info_type = "available"
alert_unit = "GB"
alert = 10.0
warning = 15.0
format = " $icon $available "
format_alt = " $icon $available / $total "

Update the block on right click, iconic behavior fr:

[[block]]
block = "disk_space"
[[block.click]]
button = "right"
update = true

Show the block only if less than 10GB is available (hiding info? main character energy):

[[block]]
block = "disk_space"
format = " $free.eng(range:..10e9) |"

🎀 Icons Used 🎀

disk_drive ($icon)

🐳 docker 🐳

Local docker daemon status. Yep, it's watching your containers 👀

✨ Configuration ✨

interval — update interval, in seconds. Default: 5
format — a string to customise the output of this block. Placeholders are listed right below. Default: " $icon $running.eng(w:1) "
socket_path — the path to the docker socket. Path expansions are supported, e.g. ~. Default: "/var/run/docker.sock"

Placeholders, slay 🫶

icon — a static icon. Icon, unit: -
total — total containers on the host. Number, unit: -
running — containers running on the host. Number, unit: -
stopped — containers stopped on the host. Number, unit: -
paused — containers paused on the host. Number, unit: -
images — total images on the host. Number, unit: -

🌸 Examples 🌸

[[block]]
block = "docker"
interval = 2
format = " $icon $running/$total "

This next one lets you show Podman status by setting the socket path (the path depends on your own setup, iykyk):

[[block]]
block = "docker"
format = " $icon $running/$total "
socket_path = "$XDG_RUNTIME_DIR/podman/podman.sock"
# socket_path = "/run/user/1000/podman/podman.sock"

🎀 Icons Used 🎀

docker ($icon)

🌍 external_ip 🌍

Your external IP address plus a whole bunch of info about it. Literally a glow-up for your bar ✨

✨ Configuration ✨

format — a string to customise the output of this block. Placeholders below. Default: " $ip $country_flag "
interval — interval in seconds for automatic updates. Default: 300
autolocate_interval — how long, in seconds, to reuse the last result from the geolocation service instead of contacting it again. Kept small by default so network changes get picked up promptly. Default: 1
with_network_manager — if true, listen for NetworkManager events and update the IP immediately if there was a change. Default: true
use_ipv4 — if true, use IPv4 for obtaining all info. Default: false

Placeholder city, population: you 💅

ip — the external IP address, as seen from a remote server. Text, unit: -
version — IPv4 or IPv6. Text, unit: -
city — city name, such as “San Francisco”. Text, unit: -
region — region name, such as “California”. Text, unit: -
region_code — region code, such as “CA” for California. Text, unit: -
country — country code (2 letter, ISO 3166-1 alpha-2). Text, unit: -
country_name — short country name. Text, unit: -
country_code — country code (2 letter, ISO 3166-1 alpha-2). Text, unit: -
country_code_iso3 — country code (3 letter, ISO 3166-1 alpha-3). Text, unit: -
country_capital — capital of the country. Text, unit: -
country_tld — country specific TLD (top-level domain). Text, unit: -
continent_code — continent code. Text, unit: -
in_eu — region code, such as “CA”. Flag, unit: -
postal — ZIP / Postal code. Text, unit: -
latitude — latitude. Number, unit: - (TODO: make degrees?)
longitude — longitude. Number, unit: - (TODO: make degrees?)
timezone — city. Text, unit: -
utc_offset — UTC offset (with daylight saving time) as +HHMM or -HHMM (HH is hours, MM is minutes). Text, unit: -
country_calling_code — country calling code (dial in code, comma separated). Text, unit: -
currency — currency code (ISO 4217). Text, unit: -
currency_name — currency name. Text, unit: -
languages — languages spoken (comma separated 2 or 3 letter ISO 639 code with optional hyphen separated country suffix). Text, unit: -
country_area — area of the country (in sq km). Number, unit: -
country_population — population of the country. Number, unit: -
timezone — time zone. Text, unit: -
org — organization. Text, unit: -
asn — autonomous system (AS). Text, unit: -
country_flag — flag of the country. Text (glyph), unit: -

Not a glitch bestie — timezone really does show up twice in the list. Both are in the original, so both stay 💜

🌸 Example 🌸

[[block]]
block = "external_ip"
format = " $ip $country_code "

📝 Notes 📝

All the information comes from https://ipapi.co/json/. Check their documentation here: https://ipapi.co/api/#complete-location5

Okay so real quick on the geolocation refresh sched, because it's lowkey clever 👀

The IP gets queried:

When i3status-rs starts
When a signal comes in over D-Bus about a network configuration change
Every 5 minutes

That periodic refresh is there on purpose — it's catching IP updates that don't fire off a notification, like when your router refreshes the IP. Sneaky ones. 🙈

If the service reports rate limiting, the block just keeps showing the last known IP and waits out the geolocator's rate_limit_interval (10 minutes by default) before it asks again. No spamming, we're polite. 💅

Flags: heads up bestie, these are not icons — they're unicode glyphs. You'll need a font that actually includes them. Tested with: https://www.babelstone.co.uk/Fonts/Flags.html

focused_window

Currently focused window 🪟

This block shows the title and/or the active marks (when you're running it with sway/i3) of whatever window is focused right now. Supported WMs are: sway, i3 and most wlroots-based compositors. Wanna know more? Peep the driver option. ✨

Configuration

format — A string to customise the output of this block. See below for available placeholders. Default: " $title.str(max_w:21) |"
driver — Which driver to use. Default: "auto". Available values:
- sway_ipc — for i3 and sway
- wlr_toplevel_management — for Wayland compositors that implement wlr-foreign-toplevel-management-unstable-v1 (https://gitlab.freedesktop.org/wlroots/wlr-protocols/-/blob/master/unstable/wlr-foreign-toplevel-management-unstable-v1.xml)
- auto — try to automatically guess which driver to use

Placeholders 🎀

title — Window's title (may be absent) — Type: Text — Unit: -
marks — Window's marks (present only with sway/i3) — Type: Text — Unit: -
visible_marks — Window's marks that do not start with _ (present only with sway/i3) — Type: Text — Unit: -

Example

[[block]]
block = "focused_window"
[block.format]
full = " $title.str(max_w:15) |"
short = " $title.str(max_w:10) |"

And this next example — instead of hiding the block when the window's title is empty, it displays Missing:

[[block]]
block = "focused_window"
format = " $title.str(0,21) | Missing "

github

The number of GitHub notifications 🐙🔔

This block shows the unread notification count for a GitHub account. You need a GitHub personal access token with the notifications scope, and you gotta pass it in using the I3RS_GITHUB_TOKEN environment variable or the token configuration option. Optionally, the colour of the block is determined by the highest notification in these lists, from highest to lowest: critical, warning, info, good. So like, the drama level of your notifs decides the vibe. 💀

Configuration

format — A string to customise the output of this block. See below for available placeholders. Default: " $icon $total.eng(w:1) "
interval — Update interval in seconds. Default: 30
token — A GitHub personal access token with the notifications scope. Default: None
hide_if_total_is_zero — Hide this block if the total count of notifications is zero. Default: false
critical — List of notification types that change the block to the critical colour. Default: None
warning — List of notification types that change the block to the warning colour. Default: None
info — List of notification types that change the block to the info colour. Default: None
good — List of notification types that change the block to the good colour. Default: None

All the placeholders are numbers without a unit. 🧮

icon — A static icon
total — The total number of notifications
assign — You were assigned to the issue
author — You created the thread
comment — You commented on the thread
ci_activity — A GitHub Actions workflow run that you triggered was completed
invitation — You accepted an invitation to contribute to the repository
manual — You subscribed to the thread (via an issue or pull request)
mention — You were specifically @mentioned in the content
review_requested — You, or a team you're a member of, were requested to review a pull request
security_alert — GitHub discovered a security vulnerability in your repository
state_change — You changed the thread state (for example, closing an issue or merging a pull request)
subscribed — You're watching the repository
team_mention — You were on a team that was mentioned

Examples

[[block]]
block = "github"
format = " $icon $total.eng(w:1)|$mention.eng(w:1) "
interval = 60
token = "..."

[[block]]
block = "github"
token = "..."
format = " $icon $total.eng(w:1) "
info = ["total"]
warning = ["mention","review_requested"]
hide_if_total_is_zero = true

Icons Used

github ($icon)

hueshift

Manage display temperature 🌡️🌈

This block displays the current color temperature in Kelvin. When you scroll on the block, the color temperature changes. A left click on the block sets the color temperature to click_temp, which is 6500K by default. A right click completely resets the color temperature back to its default value (6500K). Scroll to vibe, click to commit, right-click to ~heal~. 💅

Configuration

format — A string to customise the output of this block. See below for available placeholders. Default: " $temperature "
step — The step color temperature is in/decreased in Kelvin. Default: 100
hue_shifter — Program used to control screen color. Default: Detect automatically
max_temp — Max color temperature in Kelvin. Default: 10000
min_temp — Min color temperature in Kelvin. Default: 1000
click_temp — Left click color temperature in Kelvin. Default: 6500

Placeholders ✨

temperature — Current temperature — Type: Number — Unit: -
set_click_temp — Left
reset — Right
temperature_up — Wheel Up
temperature_down — Wheel Down

That's the whole mouse vibe, bestie — those are the defaults, no cap. 💅

✨ Available Hue Shifters ✨

Okay so here's the shifter menu, and each one is picky about which display server it lives on:

"redshift" — X11 only 🖥️
"sct" — X11 only
"xsct" — X11 only
"gammastep" — X11 and Wayland, versatile queen 👑
"wl_gammarelay" — Wayland only 🌈
"wl_gammarelay_rs" — Wayland only
"wlsunset" — Wayland only

Heads up: at the moment, only wl_gammarelay and wl_gammarelay_rs subscribe to the events and actually update the bar when the temperature is modified externally. Also — and this is lowkey the important bit — these are the only drivers at the moment that work under Wayland without flickering. 😭 No flicker era fr fr.

🌸 Example 🌸

[[block]]
block = "hueshift"
hue_shifter = "redshift"
step = 50
click_temp = 3500

There's a hard limit on max_temp set to 10000K, and the same deal for min_temp, which is 1000K. The step has a hard limit too, defined as 500K, specifically to avoid too brutal changes. Like, we're protecting you from yourself here. 🫶

🦋 kdeconnect 🦋

KDEConnect indicator — it shows info from whichever device is currently connected in KDEConnect, and it updates asynchronously, so no waiting around. ✨

Block colours get updated based on the battery level… unless all bat_* thresholds are set to 0, in which case the block colours depend on the notification count instead. Choose your fighter. 💀

Configuration

device_id — Device ID as per the output of kdeconnect --list-devices. Default: chooses the first found device, if any. 🎀
format — A string to customise the output of this block. See below for available placeholders. Default: " $icon $name{ $bat_icon $bat_charge|}{ $notif_icon|}"
format_disconnected — Same as format but when the device is disconnected. Default: " $icon "
format_missing — Same as format but when the device does not exist. Default: " $icon x "
bat_info — Min battery level below which state is set to info. Default: 60
bat_good — Min battery level below which state is set to good. Default: 60
bat_warning — Min battery level below which state is set to warning. Default: 30
bat_critical — Min battery level below which state is set to critical. Default: 15

Placeholders, aka the fun part 🧚:

icon — Icon based on connection's status. Type: Icon, Unit: -
bat_icon — Battery level indicator (only when connected and if supported). Type: Icon, Unit: -
bat_charge — Battery charge level (only when connected and if supported). Type: Number, Unit: %
network_icon — Cell Network indicator (only when connected and if supported). Type: Icon, Unit: -
network_type — Cell Network type (only when connected and if supported). Type: Text, Unit: -
network_strength — Cell Network level (only when connected and if supported). Type: Number, Unit: %
notif_icon — Only when connected and there are notifications. Type: Icon, Unit: -
notif_count — Number of notifications on your phone (only when connected and non-zero). Type: Number, Unit: -
name — Name of your device as reported by KDEConnect (if available). Type: Text, Unit: -

Example

This one does not show the name, and does not set the "good" state:

[[block]]
block = "kdeconnect"
format = " $icon {$bat_icon $bat_charge |}{$notif_icon |}{$network_icon$network_strength $network_type |}"
bat_good = 101

Icons Used

bat ($bat_icon, as a progression) 🔋
bat_charging ($bat_icon, as a progression) ⚡
net_cellular ($network_icon, as a progression) 📶
notification ($notif_icon) 🔔
phone ($icon, in format) 📱
phone_disconnected ($icon, in disconnected_format missing_format) 🙈

⌨️ keyboard_layout ⌨️

Keyboard layout indicator, and bestie there are six drivers available:

xkbevent — which can read asynchronous updates from the x11 events
setxkbmap (alias for xkbevent) — DEPRECATED 💀
xkbswitch (alias for xkbevent) — DEPRECATED 💀
localebus — which can read asynchronous updates from the systemd org.freedesktop.locale1 D-Bus path
kbddbus — which uses kbdd to monitor per-window layout changes via DBus
sway — which can read asynchronous updates from the sway IPC 🌊

setxkbmap and xkbswitch are deprecated and will be removed in v0.35.0. Consider this your two-business-day notice. 😭

Which of these methods is appropriate will depend on your system setup. iykyk.

Configuration

driver — One of "xkbevent", "setxkbmap", "xkbswitch", "localebus", "kbddbus" or "sway", depending on your system. Default: "xkbevent"
interval — Update interval, in seconds. Default: 60
DEPRECATED — Only used by the "setxkbmap" driver.
format — A string to customise the output of this block. See below for available placeholders. Default: " $layout "
sway_kb_identifier — Identifier of the device you want to monitor, as found in the output of swaymsg -t get_inputs. Default: defaults to first input found
mappings — Map layout (variant) to custom short name. Default: None

interval is deprecated and will be removed in v0.35.0. ✨

Placeholders:

layout — Keyboard layout name. Type: String
variant — Keyboard variant name or N/A if not applicable. Type: String

Examples

Listen to D-Bus for changes:

[[block]]
block = "keyboard_layout"
driver = "localebus"

Listen to kbdd for changes — the text is in the following format: "English (US)" - {$layout ($variant)}. Use block.mappings to override with shorter names as shown below. Also use format = " $layout ($variant) " to see the full text to map, or you can use:

dbus-monitor interface=ru.gentoo.kbdd

…to see the exact variant spelling. 🕵️‍♀️

[[block]]
block = "keyboard_layout"
driver = "kbddbus"
[block.mappings]
"English (US)" = "us"
"Bulgarian (new phonetic)" = "bg"

Listen to sway for changes:

[[block]]
block = "keyboard_layout"
driver = "sway"
sway_kb_identifier = "1133:49706:Gaming_Keyboard_G110"

Listen to sway for changes and override mappings:

[[block]]
block = "keyboard_layout"
driver = "sway"
format = " $layout "
[block.mappings]
"English (Workman)" = "EN"
"Russian (N/A)" = "RU"

Listen to xkb events for changes:

[[block]]
block = "keyboard_layout"
driver = "xkbevent"

🍓 load 🍓

System load average. The classic. The icon. ⭐

Configuration

format — A string to customise the output of this block. See below for available placeholders. Default: " $icon $1m.eng(w:4) "
interval — Update interval in seconds. Default: 3
info — Minimum load, where state is set to info. Default: 0.3
warning — Minimum load, where state is set to warning. Default: 0.6
critical — Minimum load, where state is set to critical. Default: 0.9

Placeholders:

icon — A static icon. Type: Icon, Unit: -
1m — 1 minute load average. Type: Number, Unit: -
5m — 5 minute load average. Type: Number, Unit: -
15m — 15 minute load average. Type: Number, Unit: -

Example

[[block]]
block = "load"
format = " $icon 1min avg: $1m.eng(w:4) "
interval = 1

Icons Used

cogs ($icon) ⚙️

💌 maildir 💌

Unread mail. Only supports maildir format — no mbox, no pigeonholes, no vibes beyond that, sorry bestie. 🙈

Important! You need to enable the maildir feature to use this block:

cargo build --release --features maildir

Slay that build flag. 🔥

✨ Configuration ✨

okay so we’re still in the maildir block, bestie — here’s the config tea:

format — a string that customises this block’s output. Peep the placeholders below. Default: " $icon $status ".
inboxes — list of maildir inboxes to look for mails in. Supports path/glob expansions (e.g. ~ and *). Default: Required.
threshold_warning — number of unread mails where state is set to warning. Default: 1.
threshold_critical — number of unread mails where state is set to critical. Default: 10.
interval — update interval, in seconds. Default: 5.
display_type — which part of the maildir to count: "new", "cur", or "all". Default: "new".

Placeholders? Say less:

icon — a static icon. Type: Icon. Unit: -.
status — number of emails. Type: Number. Unit: -.

✨ Examples ✨

[[block]]
block = "maildir"
interval = 60
inboxes = ["~/mail/local", "~/maildir/account1/*"]
threshold_warning = 1
threshold_critical = 10
display_type = "new"

✨ Icons Used ✨

mail ($icon)

🧠 memory 🧠

Memory and swap usage. literally the “am I about to run out of RAM” block.

✨ Configuration ✨

format — a [MultiFormat][MaybeMultiFormatConfig] string to customise the output of this block when in “Memory” view. See below for available placeholders. Default: [" $icon $mem_used.eng(prefix:Mi)/$mem_total.eng(prefix:Mi)($mem_used_percents.eng(w:2)) "].
interval — update interval in seconds. Default: 5.
warning_mem — percentage of memory usage, where state is set to warning. Default: 80.0.
warning_swap — percentage of swap usage, where state is set to warning. Default: 80.0.
critical_mem — percentage of memory usage, where state is set to critical. Default: 95.0.
critical_swap — percentage of swap usage, where state is set to critical. Default: 95.0.

Placeholders, aka the memory lore:

icon — memory icon. Type: Icon. Unit: -.
icon_swap — swap icon. Type: Icon. Unit: -.
mem_total — total physical ram available. Type: Number. Unit: Bytes.
mem_free — free memory not yet used by the kernel or userspace (in general you should use mem_avail). Type: Number. Unit: Bytes.
mem_free_percents — as above but as a percentage of total memory. Type: Number. Unit: Percents.
mem_avail — kernel estimate of usable free memory which includes cached memory and buffers. Type: Number. Unit: Bytes.
mem_avail_percents — as above but as a percentage of total memory. Type: Number. Unit: Percents.
mem_total_used — mem_total - mem_free. Type: Number. Unit: Bytes.
mem_total_used_percents — as above but as a percentage of total memory. Type: Number. Unit: Percents.
mem_used — memory used, excluding cached memory and buffers; same as htop’s green bar. Type: Number. Unit: Bytes.
mem_used_percents — as above but as a percentage of total memory. Type: Number. Unit: Percents.
buffers — buffers, similar to htop’s blue bar. Type: Number. Unit: Bytes.
buffers_percent — as above but as a percentage of total memory. Type: Number. Unit: Percents.
cached — cached memory (taking into account ZFS ARC cache), similar to htop’s yellow bar. Type: Number. Unit: Bytes.
cached_percent — as above but as a percentage of total memory. Type: Number. Unit: Percents.
swap_total — swap total. Type: Number. Unit: Bytes.
swap_free — swap free. Type: Number. Unit: Bytes.
swap_free_percents — as above but as a percentage of total memory. Type: Number. Unit: Percents.
swap_used — swap used. Type: Number. Unit: Bytes.
swap_used_percents — as above but as a percentage of total memory. Type: Number. Unit: Percents.
zram_compressed — compressed zram memory usage. Type: Number. Unit: Bytes.
zram_decompressed — decompressed zram memory usage. Type: Number. Unit: Bytes.
`zram_comp_ratio' — ratio of the decompressed/compressed zram memory. Type: Number. Unit: -.
zswap_compressed — compressed zswap memory usage (>=Linux 5.19). Type: Number. Unit: Bytes.
zswap_decompressed — decompressed zswap memory usage (>=Linux 5.19). Type: Number. Unit: Bytes.
zswap_decompressed_percents — as above but as a percentage of total zswap memory (>=Linux 5.19). Type: Number. Unit: Percents.
`zswap_comp_ratio' — ratio of the decompressed/compressed zswap memory (>=Linux 5.19). Type: Number. Unit: -.

Actions, because clicking is a love language:

toggle_format — toggles between format and format_alt. Default button: -. DEPRECATED.
next_format — switches to the next format in the list. Default button: Left.
prev_format — switches to the previous format in the list. Default button: Right.

✨ Examples ✨

[[block]]
block = "memory"
format = " $icon $mem_used_percents.eng(w:1) "
format_alt = " $icon_swap $swap_free.eng(w:3,u:B,p:Mi)/$swap_total.eng(w:3,u:B,p:Mi)($swap_used_percents.eng(w:2)) "
interval = 30
warning_mem = 70
critical_mem = 90

Show swap and hide if it is zero:

[[block]]
block = "memory"
format = " $icon $swap_used.eng(range:1..) |"

✨ Icons Used ✨

memory_mem ($icon)
memory_swap ($icon_swap)

A custom menu. This block lets you quickly run a custom shell command. Left-click on this block to activate it, then scroll through configured items. Left-click on the item to run it and optionally confirm your action by left-clicking again. Right-click any time to deactivate this block.

✨ Configuration ✨

text — text that will be displayed when the block is inactive. Default: Required.
items — a list of “items”. See examples below. Default: Required.

✨ Example ✨

[[block]]
block = "menu"
text = "\uf011"
[[block.items]]
display = " -&gt;   Sleep   &lt;-"
cmd = "systemctl suspend"
[[block.items]]
display = " -&gt; Power Off &lt;-"
cmd = "poweroff"
confirm_msg = "Are you sure you want to power off?"
[[block.items]]
display = " -&gt;  Reboot   &lt;-"
cmd = "reboot"
confirm_msg = "Are you sure you want to reboot?"

🎵 music 🎵

The current song title and artist. also gives you buttons for play/pause, previous and next. iconic behavior.

Supports all music players that implement the MediaPlayer2 Interface. This includes:

Spotify
VLC
mpd (via mpDris2)

and many others.

By default the block tracks all players available on the MPRIS bus. Right clicking on the block will cycle it to the next player. You can pin the widget to a given player via the “player” setting. 💅

Configuration

okay so here's the whole config table for the music block, bestie — every key, every value, every default, nothing skipped 💖

format — a [MultiFormat][MaybeMultiFormatConfig] string so you can customise the output of this block. See below for the available placeholders. Default:

[" $icon {$combo.str(max_w:25,rot_interval:0.5) $play |}"]

player — Name(s) of the music player(s) MPRIS interface. This can be either a single music player name or an array of music player names. Run

busctl --user list | grep "org.mpris.MediaPlayer2." | cut -d' ' -f1

and the name is the part after org.mpris.MediaPlayer2.. Default: None.

interface_name_exclude — a list of regex patterns for player MPRIS interface names to ignore. Default: ["playerctld"].
separator — the string inserted between artist and title. Default: " - ".
seek_step_secs — a positive number of seconds to seek forward/backward when scrolling on the bar. Does not need to be an integer. Default: 1.
seek_forward_step_secs — a positive number of seconds to seek forward when scrolling on the bar. Does not need to be an integer. Default: seek_step_secs.
seek_backward_step_secs — a positive number of seconds to seek backward when scrolling on the bar. Does not need to be an integer. Default: seek_step_secs.
volume_step — the percent volume level is increased/decreased for the selected audio device when scrolling. Capped automatically at 50. Default: 5.

Note: all placeholders except icon can be absent. Peep the examples below to learn how to handle that, fr fr 🙈

Placeholders ✨

icon — a static icon. Type: Icon.
artist — current artist. Type: Text.
title — current title. Type: Text.
url — current song url. Type: Text.
combo — resolves to "$title[sep]$artist", "$artist", "$title", or "$url" depending on what information is available. [sep] is set by the separator option. Type: Text.
combo_reversed — resolves to "$artist[sep]$title", "$artist", "$title", or "$url" depending on what information is available. [sep] is set by the separator option. Type: Text.
player — name of the current player (taken from the last part of its MPRIS bus name). Type: Text.
avail — total number of players available to switch between. Type: Number.
cur — the current player index of the available players. Type: Number.
play — Play/Pause button. Type: Clickable icon.
next — Next button. Type: Clickable icon.
prev — Previous button. Type: Clickable icon.
volume_icon — icon based on volume. Missing if unsupported. Type: Icon.
volume — current volume. Missing if muted or unsupported. Type: Number.

Widgets 🎀

play_pause_btn → $play
next_btn → $next
prev_btn → $prev

Actions 💅

play_pause — Left on play_pause_btn
next — Left on next_btn
prev — Left on prev_btn
next_player — Right
seek_forward — Wheel Up
seek_backward — Wheel Down
volume_up — -
volume_down — -
toggle_format DEPRECATED — -
next_format — Left
prev_format — -

Examples 🦋

Show the currently playing song on Spotify only, with play & next buttons, and limit the width to 20 characters:

[[block]]
block = "music"
format = " $icon {$combo.str(max_w:20) $play $next |}"
player = "spotify"

Same thing for any compatible player — takes the first active one on the bus, but ignores mpd or anything with kdeconnect in the name:

[[block]]
block = "music"
format = " $icon {$combo.str(max_w:20) $play $next |}"
interface_name_exclude = [".*kdeconnect.*", "mpd"]

Same as above, but the text rotates (iconic behaviour, honestly):

[[block]]
block = "music"
format = " $icon {$combo.str(max_w:20,rot_interval:0.5) $play $next |}"
interface_name_exclude = [".*kdeconnect.*", "mpd"]

Click anywhere to play/pause, middle click to toggle format:

[[block]]
block = "music"
format = " format 1 "
format_alt = " format 2 "
[[block.click]]
button = "left"
action = "play_pause"
[[block.click]]
button = "middle"
widget = "."
action = "next_format"

Scroll to change the player volume, use the forward and back buttons to seek:

[[block]]
block = "music"
format = " $icon $volume_icon $combo $play $next| "
seek_step_secs = 10
[[block.click]]
button = "up"
action = "volume_up"
[[block.click]]
button = "down"
action = "volume_down"
[[block.click]]
button = "forward"
action = "seek_forward"
[[block.click]]
button = "back"
action = "seek_backward"

Icons Used 🌸

music ($icon)
music_next ($next)
music_pause ($play)
music_play ($play)
music_prev ($prev)
volume ($volume_icon, as a progression)

net 🌐

Network information, bestie.

This block uses sysfs and netlink and thus does not require any external dependencies. Zero. None. We love a low-maintenance queen 👑

Configuration

device — network interface to monitor (as specified in /sys/class/net/). Supports regex. Default: if not set, device will be automatically selected every interval.
interval — update interval in seconds. Default: 2.
format — a [MultiFormat][MaybeMultiFormatConfig] string to customise the output of this block. See below for available placeholders. Default:

[" $icon ^icon_net_down $speed_down.eng(prefix:K) ^icon_net_up $speed_up.eng(prefix:K) "]

inactive_format — same as format but for when the interface is inactive. Default: " $icon Down ".
missing_format — same as format but for when the device is missing. Default: " × ".

Actions ✨

toggle_format DEPRECATED — toggles between format and format_alt. Default button: -.
next_format — switches to the next format in the list. Default button: Left.
prev_format — switches to the previous format in the list. Default button: Right.
icon — Icon based on the device's type ✨ (type: Icon, unit: none)
speed_down — Download speed 🡇 (type: Number, unit: bytes per second)
speed_up — Upload speed 🡅 (type: Number, unit: bytes per second)
graph_down — Download speed graph 📉 (type: Text, unit: none)
graph_up — Upload speed graph 📈 (type: Text, unit: none)
device — The name of device (type: Text, unit: none)
ssid — Network SSID (WiFi only) (type: Text, unit: none)
frequency — WiFi frequency (type: Number, unit: Hz)
signal_strength — WiFi signal (type: Number, unit: %)
bitrate — WiFi connection bitrate (type: Number, unit: bits per second)
ip — IPv4 address of the iface (type: Text, unit: none)
ipv6 — IPv6 address of the iface (type: Text, unit: none)
nameserver — Nameserver (type: Text, unit: none)
enabled — Present if the device is switched on (not turned off with rfkill or ip link set down) (type: Flag, unit: none)

🌸 Example

Display WiFi info if available 💖

[[block]]
block = "net"
format = " $icon {$signal_strength $ssid $frequency|Wired connection} via $device "

Display exact device — like, only that one, no cap:

[[block]]
block = "net"
device = "^wlo0$"

Tell a WiFi device that is not connected from one that is switched off (with rfkill for example) 🫶:

[[block]]
block = "net"
device = "^wlan0$"
format = " $icon $signal_strength "
inactive_format = " {$enabled{not connected}|switched off} "

🎀 Icons Used

net_loopback ($icon)
net_vpn ($icon)
net_wired ($icon)
net_wireless ($icon, as a progression)
net_up (^icon_net_up)
net_down (^icon_net_down)

🔔 notify

Display and toggle the state of notifications daemon. Literally the notification babysitter bestie 💅

Left-clicking on this block will enable/disable notifications.

Configuration

driver — Which notifications daemon is running. Available drivers are: "dunst" and "swaync". Default: "dunst"
format — A string to customise the output of this block. See below for available placeholders. Default: " $icon "

Placeholders, bestie ✨:

icon — Icon based on notification's state (type: Icon, unit: none)
notification_count[1] — The number of notification (omitted if 0) (type: Number, unit: none)
history_count[2] — The number of notification in history (omitted if 0) (type: Number, unit: none)
paused — Present only if notifications are disabled (type: Flag, unit: none)

Actions and their default buttons 🎀:

toggle_paused — Default button: Left
show — Default button: -
show_all — Default button: -

The show and show_all actions are the same for SwayNC. 👑

Examples

How to use paused flag:

[[block]]
block = "notify"
format = " $icon {$paused{Off}|On} "

How to use notification_count:

[[block]]
block = "notify"
format = " $icon {($notification_count.eng(w:1)) |}"

How to remap actions 🔥:

[[block]]
block = "notify"
driver = "swaync"
[[block.click]]
button = "left"
action = "show"
[[block.click]]
button = "right"
action = "toggle_paused"

🦋 Icons Used

bell ($icon)
bell-slash ($icon)

📬 notmuch

Count of notmuch messages. It's giving ✨inbox anxiety✨ but make it cute.

This block queries a notmuch database and displays the count of messages.

The simplest configuration will return the total count of messages in the notmuch database stored at $HOME/.mail

Heads up! You need to enable the notmuch feature to use this block 🫶: cargo build --release --features notmuch

Configuration

format — A string to customise the output of this block. See below for available placeholders. Default: " $icon $count "
maildir — Path to the directory containing the notmuch database. Supports path expansions e.g. ~. Default: ~/.mail
query — Query to run on the database. Default: ""
threshold_critical — Mail count that triggers critical state. Default: 99999
threshold_warning — Mail count that triggers warning state. Default: 99999
threshold_good — Mail count that triggers good state. Default: 99999
threshold_info — Mail count that triggers info state. Default: 99999
interval — Update interval in seconds. Default: 10

Placeholders 💜:

icon — A static icon (type: Icon, unit: none)
count — Number of messages for the query (type: Number, unit: none)

Example

[[block]]
block = "notmuch"
query = "tag:alert and not tag:trash"
threshold_warning = 1
threshold_critical = 10
[[block.click]]
button = "left"
update = true

🍓 Icons Used

mail ($icon)

🎮 nvidia_gpu

Display the stats of your NVidia GPU. Frames go brrr ✨🔥

By default show_temperature shows the used memory. Clicking the left mouse on the “temperature” part of the block will alternate it between showing used or total available memory.

Clicking the left mouse button on the “fan speed” part of the block will cause it to enter into a fan speed setting mode. In this mode you can scroll the mouse wheel over the block to change the fan speeds, and left click to exit the mode.

Requires nvidia-smi for displaying info and nvidia_settings for setting fan speed. 👑

On laptops with switchable graphics, nvidia-smi powers on the dedicated GPU every time it runs, which keeps the GPU awake and raises power consumption. Increase interval or avoid this block if that matters on battery. 😭 (fr fr, battery bestie, watch out)

Configuration

gpu_id — GPU id in system. Default: 0
format — A string to customise the output of this block. See below for available placeholders. Default: " $icon $utilization $memory $temperature "
interval — Update interval in seconds. Default: 1
idle — Maximum temperature, below which state is set to idle. Default: 50
good — Maximum temperature, below which state is set to good. Default: 70
info — Maximum temperature, below which state is set to info. Default: 75
warning — Maximum temperature, below which state is set to warning. Default: 80

Placeholders 🌈:

icon — Icon, unit: none
name — Text, unit: none
utilization — Number, percents
memory — Number, bytes
temperature — Number, degrees
fan_speed — Number, percents
clocks — Number, hertz
power — Number, watts

Widgets → placeholders 🎀:

mem_btn → $memory
fan_btn → $fan_speed

Actions and their default buttons 💅:

toggle_mem_total — Left on mem_btn
toggle_fan_controlled — Left on fan_btn
fan_speed_up — Wheel Up on fan_btn
fan_speed_down — Wheel Down on fan_btn

Example

[[block]]
block = "nvidia_gpu"
interval = 1
format = " $icon GT 1030 $utilization $temperature $clocks "

💀 Icons Used

gpu ($icon)

TODO

Provide a mappings option similar to keyboard_layout's to map GPU names to labels? 🤔

📦 packages

Pending updates for different package manager like apt, pacman, etc. The "you have 47 updates bestie" block 😭📦

Currently, these package managers are supported:

apk for Alpine Linux
apt for Debian/Ubuntu-based systems
aur for Arch-based systems
brew for the Homebrew Package Manager
dnf for Fedora-based systems
flatpak for Flatpak packages
pacman for Arch-based systems
snap for Snap packages
xbps for Void Linux
zypper for openSUSE

Configuration

Okay bestie, here's the config tea ☕ — every key, its vibe, and what it defaults to when you don't say anything:

interval — Update interval, in seconds. Default: 600.
package_manager — Which package manager(s) to check for updates. Default: automatically derived from your format templates, but you can use it to influence the $total value.
format — A string to customise the output of this block. Peep the placeholders below for what you can drop in. Default: " $icon $total.eng(w:1) ".
format_singular — Same as format, but for when exactly one update is available. Default: " $icon $total.eng(w:1) ".
format_up_to_date — Same as format, but for when no updates are available. Default: " $icon $total.eng(w:1) ".
warning_updates_regex — Display the block as a warning if updates matching this regex are available. Default: None.
critical_updates_regex — Display the block as critical if updates matching this regex are available. Default: None.
ignore_updates_regex — Doesn't include updates matching this regex in the count. Default: None.
ignore_phased_updates — Doesn't include potentially held-back phased updates in the count (for Debian/Ubuntu-based systems). Default: false.
aur_command — The AUR command used to check available updates, which outputs in the same format as pacman, e.g. yay -Qua (for Arch-based systems). Required if $aur is used.

Placeholders 💖

These are the little cuties you can slot into your format strings:

icon — A static icon. Type: Icon. Unit: -.
apk — Number of updates available in Alpine Linux. Type: Number. Unit: -.
apt — Number of updates available in Debian/Ubuntu-based systems. Type: Number. Unit: -.
aur — Number of updates available in Arch-based systems. Type: Number. Unit: -.
brew — Number of updates available in the Homebrew Package Manager. Type: Number. Unit: -.
dnf — Number of updates available in Fedora-based systems. Type: Number. Unit: -.
flatpak — Number of updates available in Flatpak packages. Type: Number. Unit: -.
pacman — Number of updates available in Arch-based systems. Type: Number. Unit: -.
snap — Number of updates available in Snap packages. Type: Number. Unit: -.
xbps — Number of updates available in Void Linux. Type: Number. Unit: -.
zypper — Number of updates available in openSUSE. Type: Number. Unit: -.
total — Number of updates available in all package managers listed. Type: Number. Unit: -.

Apt 🐧

Behind the scenes this literally just uses apt, and so it can run without root privileges, i3status-rust will create its own little package database in /tmp/i3rs-apt/ — which may take up several MB or more, ngl. If you've got a custom apt config then this block may not work as expected — in that case, please open an issue, bestie 🙏

Tip: You can grab the list of available updates using

APT_CONFIG=/tmp/i3rs-apt/apt.conf apt list --upgradable

Pacman 🌈

Requires fakeroot to be installed (only required for pacman, iykyk).

Tip: You can grab the list of available updates using

fakeroot pacman -Qu --dbpath /tmp/checkup-db-i3statusrs-$USER/

If you have the CHECKUPDATES_DB env var set on your system then substitute that dir instead.

Note: pikaur may hang the whole block if there is no internet connectivity reference. In that case, try a different AUR helper. 💀

Pacman hook 🎀

Tip: On Arch Linux you can set up a pacman hook to signal i3status-rs to update after packages have been upgraded, so you won't have stale info sitting in your pacman block. Iconic behaviour, honestly.

In the block configuration, set signal = 1 (or another number if 1 is being used by some other block):

[[block]]
block = "packages"
signal = 1

Create /etc/pacman.d/hooks/i3status-rust.hook with the below contents:

[Trigger]
Operation = Upgrade
Type = Package
Target = *

[Action]
When = PostTransaction
Exec = /usr/bin/pkill -SIGRTMIN+1 i3status-rs

Example ✨

Apk-only config:

[[block]]
block = "packages"
package_manager = ["apk"]
interval = 1800
error_interval = 300
max_retries = 5
format = " $icon $apk.eng(w:1) updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
# shows dmenu with available updates. Any dmenu alternative should also work.
button = "left"
cmd = "apk --no-cache --upgradable list | dmenu -l 10"

Apt-only config

[[block]]
block = "packages"
interval = 1800
error_interval = 300
max_retries = 5
package_manager = ["apt"]
format = " $icon $apt updates available"
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
# shows dmenu with cached available updates. Any dmenu alternative should also work.
button = "left"
cmd = "APT_CONFIG=/tmp/i3rs-apt/apt.conf apt list --upgradable | tail -n +2 | rofi -dmenu"
[[block.click]]
# Updates the block on right click
button = "right"
update = true

Brew-only config:

[[block]]
block = "packages"
package_manager = ["brew"]
interval = 1800
error_interval = 300
max_retries = 5
format = " $icon $brew.eng(w:1) updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
# shows dmenu with available updates. Any dmenu alternative should also work.
button = "left"
cmd = "brew outdated | dmenu -l 10"

Dnf-only config:

[[block]]
block = "packages"
package_manager = ["dnf"]
interval = 1800
error_interval = 300
max_retries = 5
format = " $icon $dnf.eng(w:1) updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
# shows dmenu with cached available updates. Any dmenu alternative should also work.
button = "left"
cmd = "dnf list -q --upgrades | tail -n +2 | rofi -dmenu"

Flatpak-only config:

[[block]]
block = "packages"
package_manager = ["flatpak"]
interval = 1800
error_interval = 300
max_retries = 5
format = " $icon $flatpak.eng(w:1) updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
# shows dmenu with cached available updates. Any dmenu alternative should also work.
button = "left"
cmd = "flatpak remote-ls --updates --columns=ref | rofi -dmenu"

Pacman-only config:

[[block]]
block = "packages"
package_manager = ["pacman"]
interval = 600
error_interval = 300
max_retries = 5
format = " $icon $pacman updates available "
format_singular = " $icon $pacman update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
# pop-up a menu showing the available updates. Replace wofi with your favourite menu command.
button = "left"
cmd = "fakeroot pacman -Qu --dbpath /tmp/checkup-db-i3statusrs-$USER/ | wofi --show dmenu"
[[block.click]]
# Updates the block on right click
button = "right"
update = true

Pacman and AUR helper config:

[[block]]
block = "packages"
package_manager = ["pacman", "aur"]
interval = 600
error_interval = 300
max_retries = 5
format = " $icon $pacman + $aur = $total updates available "
format_singular = " $icon $total update available "
format_up_to_date = " $icon system up to date "
# aur_command should output available updates to stdout (ie behave as echo -ne "update\n")
aur_command = "yay -Qua"

Snap-only config:

[[block]]
block = "packages"
package_manager = ["snap"]
interval = 1800
error_interval = 300
max_retries = 5
format = " $icon $snap.eng(w:1) updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
# shows dmenu with available updates. Any dmenu alternative should also work.
button = "left"
cmd = "snap refresh --list | dmenu -l 10"

Xbps-only config:

[[block]]
block = "packages"
package_manager = ["xbps"]
interval = 1800
error_interval = 300
max_retries = 5
format = " $icon $xbps.eng(w:1) updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
# shows dmenu with available updates. Any dmenu alternative should also work.
button = "left"
cmd = "xbps-install -Mun | dmenu -l 10"

Zypper-only config:

[[block]]
block = "packages"
package_manager = ["zypper"]
interval = 1800
error_interval = 300
max_retries = 5
format = " $icon $zypper.eng(w:1) updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
# shows dmenu with available updates. Any dmenu alternative should also work.
button = "left"
cmd = "zypper -q list-updates | tail -n +3 | rofi -dmenu -window-title 'Upgradable packages:'"

Bestie. Multiple package managers config?? Yes queen, you can stack them. ✨

Update the list of pending updates every thirty minutes (1800 seconds):

[[block]]
block = "packages"
package_manager = ["apk", "apt", "aur", "brew", "dnf", "flatpak", "pacman", "snap", "xbps", "zypper"]
interval = 1800
error_interval = 300
max_retries = 5
format = " $icon $apk + $apt + $aur + $brew + $dnf + $flatpak + $pacman + $snap + $xbps + $zypper = $total updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
# If a linux update is available, but no ZFS package, it won't be possible to
# actually perform a system upgrade, so we show a warning.
warning_updates_regex = "(linux|linux-lts|linux-zen)"
# If ZFS is available, we know that we can and should do an upgrade, so we show
# the status as critical.
critical_updates_regex = "(zfs|zfs-lts)"

🎀 Icons Used 🎀

update ($icon)

🍅 pomodoro 🍅

A pomodoro timer — literally the focus technique that ate, ngl. Get your life together in 25 minute chunks, it's giving productivity queen 💅

🌸 Technique 🌸

There are six steps in the original technique: 1) Decide on the task to be done. 2) Set the pomodoro timer (traditionally to 25 minutes). 3) Work on the task. 4) End work when the timer rings and put a checkmark on a piece of paper. 5) If you have fewer than four checkmarks, take a short break (3–5 minutes) and then return to step 2. 6) After four pomodoros, take a longer break (15–30 minutes), reset your checkmark count to zero, then go to step 1.

Yes the paper checkmark is mandatory bestie, the whole vibe depends on it. 😭

🌈 Configuration 🌈

format — the format used when in idle, prompt, or notify states. Default: " $icon{ $message|} "
pomodoro_format — the format used when the pomodoro is running or paused. Default: " $icon $status_icon{ $completed_pomodoros.tally()|} $time_remaining.duration(hms:true) "
break_format — the format used when the pomodoro is during the break. Default: " $icon $status_icon Break: $time_remaining.duration(hms:true) "
message — message when timer expires. Default: "Pomodoro over! Take a break!"
break_message — message when break is over. Default: "Break over! Time to work!"
notify_cmd — a shell command to run as a notifier. {msg} will be substituted with either message or break_message. Default: None
blocking_cmd — is notify_cmd blocking? If it is, then pomodoro block will wait until the command finishes before proceeding. Otherwise, you will have to click on the block in order to proceed. Default: false

Lowkey important: if blocking_cmd is false you're on click duty, bestie. No free rides 👑

🦋 Placeholders 🦋

icon — a static icon. Type: Icon. Supported by: all formats.
status_icon — an icon that reflects the pomodoro state. Type: Icon. Supported by: pomodoro_format, break_format.
message — current message. Type: Text. Supported by: format.
time_remaining — how much time is left (minutes). Type: Duration. Supported by: pomodoro_format, break_format.
completed_pomodoros — the number of completed pomodoros. Type: Number. Supported by: pomodoro_format.

⭐ Example ⭐

Use swaynag as a notifier:

[[block]]
block = "pomodoro"
notify_cmd = "swaynag -m '{msg}'"
blocking_cmd = true

Use notify-send as a notifier:

[[block]]
block = "pomodoro"
notify_cmd = "notify-send '{msg}'"
blocking_cmd = false

💖 Icons Used 💖

pomodoro ($icon)
pomodoro_started ($status_icon, in pomodoro_format)
pomodoro_stopped ($status_icon, in format)
pomodoro_paused ($status_icon, in pomodoro_format)
pomodoro_break ($status_icon, in break_format)

👀 privacy 👀

Privacy Monitor — it's literally watching who's watching you. Main character surveillance energy 🕵️‍♀️

🫶 Configuration 🫶

driver — the configuration of a driver (see below). Default: Required
format — [MultiFormat][MaybeMultiFormatConfig] string. Default: ["{ $icon_audio |}{ $icon_audio_sink |}{ $icon_video |}{ $icon_webcam |}{ $icon_unknown |}", "{ $icon_audio $info_audio |}{ $icon_audio_sink $info_audio_sink |}{ $icon_video $info_video |}{ $icon_webcam $info_webcam |}{ $icon_unknown $info_unknown |}"]

🧚 pipewire Options 🧚 (requires the `pipewire` feature to be enabled)

name — value: pipewire. Required: Yes. Default: None
exclude_output — an output node to ignore, example: ["HD Pro Webcam C920"]. Required: No. Default: []
exclude_input — an input node to ignore, example: ["openrgb"]. Required: No. Default: []
display — which node field should be used as a display name, options: name, description, nickname. Required: No. Default: name

💜 vl4 Options 💜

name — value: vl4. Required: Yes. Default: None
exclude_device — a device to ignore, example: ["/dev/video5"]. Required: No. Default: []
exclude_consumer — processes to ignore. Required: No. Default: ["pipewire", "wireplumber"]

🌸 Available Format Keys 🌸

icon_{audio,audio_sink,video,webcam,unknown} — a static icon. Type: Icon. Unit: -
info_{audio,audio_sink,video,webcam,unknown} — the mapping of which source are being consumed. Type: Text. Unit: -

You can use the suffixes noted above to get the following:

audio — captured audio (ex. Mic)
audio_sink — audio captured from a sink (ex. openrgb)
video — video capture (ex. screen capture)
webcam — webcam capture
unknown — anything else

🔥 Available Actions 🔥

toggle_format — toggles between format and format_alt. Default button: -. DEPRECATED
next_format — switches to the next format in the list. Default button: Left
prev_format — switches to the previous format in the list. Default button: Right

Heads up bestie: toggle_format is flagged DEPRECATED in the original docs. Use the next/prev ones, iykyk 💅

🍓 Example 🍓

[[block]]
block = "privacy"
[[block.driver]]
name = "v4l"
[[block.driver]]
name = "pipewire"
exclude_input = ["openrgb"]
display = "nickname"

👑 Icons Used 👑

microphone ($icon_audio)
volume ($icon_audio_sink)
xrandr ($icon_video)
webcam ($icon_webcam)
- unknown ($icon_unknown)

rofication 🎀

The number of pending notifications chilling in rofication-daemon

Lowkey a different color pops up if there are critical notifications, so you can spot the drama at a glance 🔥

Configuration

interval — Refresh rate in seconds. Default: 1
format — A string to customise the output of this block. See below for placeholders. Default: " $icon $num.eng(w:1) "
socket_path — Socket path for the rofication daemon. Supports path expansions e.g. ~. Default: "/tmp/rofi_notification_daemon"

Placeholders bestie:

icon — A static icon. Type: Icon, Unit: -
num — Number of pending notifications. Type: Number, Unit: -

Example

[[block]]
block = "rofication"
interval = 1
socket_path = "/tmp/rofi_notification_daemon"
[[block.click]]
button = "left"
cmd = "rofication-gui"

Icons Used

bell ($icon)

scratchpad 🦋

Scratchpad indicator — it literally just tells you what's up with your scratchpad 💅

Configuration

format — A string to customise the output of this block. Default: $icon $count.eng(range:1..) \|

Placeholders:

icon — A static icon. Type: Icon, Unit: -
count — Number of windows in scratchpad. Type: Number, Unit: -

Example

[[block]]
block = "scratchpad"

Icons Used

scratchpad ($icon)

service_status ⭐

Display the status of a service — iconic for keeping an eye on your daemons ngl 🫶

Right now only systemd is supported. Periodt.

Configuration

driver — Which init system is running the service. Available drivers are: "systemd". Default: "systemd"
service — The name of the service. Default: Required
user — If true, monitor the status of a user service instead of a system service. Default: false
active_format — A string to customise the output of this block. See below for available placeholders. Default: " $service active "
inactive_format — A string to customise the output of this block. See below for available placeholders. Default: " $service inactive "
active_state — A valid [State]. Default: [State::Idle]
inactive_state — A valid [State]. Default: [State::Critical]

Placeholders:

service — The name of the service. Type: Text, Unit: -

Example

Example using an icon, so cute:

[[block]]
block = "service_status"
service = "cups"
active_format = " ^icon_tea "
inactive_format = " no ^icon_tea "

Example overriding the default inactive_state, for when you're feeling dramatic:

[[block]]
block = "service_status"
service = "shadow"
active_format = ""
inactive_format = " Integrity of password and group files failed "
inactive_state = "Warning"

sound 💖

Volume level — the moment we've all been waiting for 🔊

This block displays the volume level (according to PulseAudio or ALSA). Right click to toggle mute, scroll to adjust volume. Slay.

Requires a PulseAudio installation or alsa-utils for ALSA. No cap.

Note that if you are using PulseAudio commands (such as pactl) to control your volume, you should select the "pulseaudio" (or "auto") driver to see volume changes that exceed 100%. Important bestie, don't skip this 💀

Configuration

driver — "auto", pipewire, "pulseaudio", "alsa". Default: "auto" (Pipewire with Pulseaudio fallback with ALSA fallback)
format — A [MultiFormat][MaybeMultiFormatConfig] string to customise the output of this block. See below for available placeholders. Default: [" $icon {$volume.eng(w:2) |}"]
name — PulseAudio device name, or the ALSA control name as found in the output of amixer -D yourdevice scontrols. Default: PulseAudio: @DEFAULT_SINK@ / ALSA: Master
device — ALSA device name, usually in the form “hw:X” or “hw:X,Y” where X is the card number and Y is the device number as found in the output of aplay -l. Default: default
device_kind — PulseAudio device kind: source or sink. Default: "sink"
natural_mapping — When using the ALSA driver, display the “mapped volume” as given by alsamixer/amixer -M, which represents the volume level more naturally with respect for the human ear. Default: false
step_width — The percent volume level is increased/decreased for the selected audio device when scrolling. Capped automatically at 50. Default: 5
max_vol — Max volume in percent that can be set via scrolling. Note it can still be set above this value if changed by another application. Default: None
show_volume_when_muted — Show the volume even if it is currently muted. Default: false
headphones_indicator — Change icon when headphones are plugged in (pulseaudio only). Default: false
mappings — Map output_name to a custom name. Default: None
mappings_use_regex — Let mappings match using regex instead of string equality. The replacement will be regex aware and can contain capture groups. Default: true
active_port_mappings — Map active_port to a custom name. The replacement will be regex aware and can contain capture groups. Default: None

Placeholders:

icon — Icon based on volume. Type: Icon, Unit: -
volume — Current volume. Missing if muted. Type: Number, Unit: %
output_name — PulseAudio or ALSA device name. Type: Text, Unit: -
output_description — PulseAudio device description, will fallback to output_name if no description is available and will be overwritten by mappings (mappings will still use output_name). Type: Text, Unit: -
active_port — Active port (same as information in Ports section of pactl list cards). Will be absent if not supported by driver or if mapped to "" in active_port_mappings. Type: Text, Unit: -

Actions, aka the fun clicky stuff 🖱️:

toggle_mute — Toggle mute. Default button: Right
volume_down — Decrease volume. Default button: Wheel Down
volume_up — Increase volume. Default button: Wheel Up
toggle_format — Toggles between format and format_alt. DEPRECATED ⚠️
next_format — Switches to the next format in the list. Default button: Left
prev_format — Switches to the previous format in the list. Default button: -

Examples

Change the default scrolling step width to 3 percent:

[[block]]
block = "sound"
step_width = 3

Change the output name shown — lowkey so useful:

[[block]]
block = "sound"
format = " $icon $output_name{ $volume|} "
[block.mappings]
"alsa_output.usb-Harman_Multimedia_JBL_Pebbles_1.0.0-00.analog-stereo" = "Speakers"
"alsa_output.pci-0000_00_1b.0.analog-stereo" = "Headset"

Since the default value for the device_kind key is sink, to display microphone block you have to use the source value. Iykyk 🎤:

[[block]]
block = "sound"
driver = "pulseaudio"
device_kind = "source"

Display warning in block if microphone if using the wrong port:

[[block]]
block = "sound"
driver = "pulseaudio"
device_kind = "source"
format = " $icon { $volume|} {$active_port |}"
[block.active_port_mappings]
"analog-input-rear-mic" = "" # Mapping to an empty string makes `$active_port` absent
"analog-input-front-mic" = "ERR!"

🎀 Icons Used

microphone_muted ($icon, as a progression)
microphone ($icon, as a progression)
volume_muted ($icon, as a progression)
volume ($icon, as a progression)
headphones ($icon)

🦋 speedtest

Ping, jitter, download, and upload speeds 💫

This block uses Cloudflare's networkquality-rs (nq) library to run a speedtest and report the ping, jitter, download speed, and upload speed. Honestly iconic of it.

You can configure the block to use custom endpoints for the speedtest, but bestie, by default Cloudflare's nq endpoints are the ones being used.

So like, for example — setting config_url to "https://mensura.cdn-apple.com/.well-known/nq" will use Apple's nq endpoints instead of Cloudflare's. Slay.

nq is based on the IETF draft: "Responsiveness under Working Conditions".

That draft defines "responsiveness", measured in Round trips Per Minute (RPM), as a useful measurement of network quality. Periodt.

💜 Configuration

format — a string to customise the output of this block. See below for available placeholders. Default: " ^icon_ping $ping.eng(prefix:m) ^icon_net_down $speed_down ^icon_net_up $speed_up "
interval — update interval in seconds. Default: 1800
config_url — the endpoint to get the responsiveness config from. See [SpeedtestConfig::config_url] for the expected format of the configuration JSON returned by this endpoint. Default: None
large_download_url — the large file endpoint which should be multiple GBs. Default: "https://h3.speed.cloudflare.com/__down?bytes=10000000000"
small_download_url — the small file endpoint which should be very small, only a few bytes. Default: "https://h3.speed.cloudflare.com/__down?bytes=10"
upload_url — the upload url which accepts an arbitrary amount of data. Default: "https://h3.speed.cloudflare.com/__up"
latency — arguments for the latency test. See table below. Default: see table below
rpm — arguments for the RPM test. See table below. Default: see table below

🌸 Latency Configuration (settings used for ping and jitter)

runs — the number of latency test runs to perform. Default: 20

⭐ RPM Configuration (settings used for `speed_down` and `speed_up`)

moving_average_distance — the number of intervals to use when calculating the moving average. Default: 4
std_tolerance — how far a measurement is allowed to be from the previous moving average before the measurement is considered unstable. Default: 0.05
trimmed_mean_percent — determines which percentile to use for averaging when calculating the trimmed mean of throughputs or RPM scores. A value of 0.95 means to only use values in the 95th percentile to calculate an average. Default: 0.95
max_loaded_connections — the maximum number of loaded connections that the test can use to saturate the network. Default: 16
interval_duration_ms — the duration between test intervals in milliseconds (ms). Default: 500 (0.5 seconds)
test_duration_ms — the overall test duration in milliseconds (ms). Default: 12_000 (12 seconds)
conn_type — the type of connection to use for the speed test. One of "h1", "h2", or "h3". Default: "h2"
upload_bytes_per_request — the number of bytes to upload per request during the speed test. Default: 100_000_000

🧚 Available Format Keys

ping — ping delay — type: Number — unit: Seconds
jitter — jitter — type: Number — unit: Seconds
speed_down — download speed — type: Number — unit: Bits per second
speed_up — upload speed — type: Number — unit: Bits per second

✨ Examples

Show only ping (with an icon):

[[block]]
block = "speedtest"
format = " ^icon_ping $ping "

Hide ping and display speed in bytes per second each using 4 characters (without icons):

[[block]]
block = "speedtest"
format = " $speed_down.eng(w:4,u:B) $speed_up(w:4,u:B) "

Advanced configuration:

[[block]]
block = "speedtest"
[block.latency]
runs = 5
[block.rpm]
conn_type = "h1"

🎀 Icons Used

ping (^icon_ping)
net_down (^icon_net_down)
net_up (^icon_net_up)

🔥 taskwarrior

The number of tasks from the taskwarrior list. Very "get your life together" of it 💅

Clicking the right mouse button on the icon cycles the view of the block through the user's filters. Cute, right?

💖 Configuration

interval — update interval in seconds. Default: 600 (10min)
warning_threshold — the threshold of pending (or started) tasks when the block turns into a warning state. Default: 10
critical_threshold — the threshold of pending (or started) tasks when the block turns into a critical state. Default: 20
filters — a list of tables describing filters (see bellow). Default: [{name = "pending", filter = "-COMPLETED -DELETED"}]
format — a string to customise the output of this block. See below for available placeholders. Default: " $icon $count.eng(w:1) "
format_singular — same as format but for when exactly one task is pending. Default: " $icon $count.eng(w:1) "
format_everything_done — same as format but for when all tasks are completed. Default: " $icon $count.eng(w:1) "
data_location — directory in which taskwarrior stores its data files. Supports path expansions e.g. ~. Default: "~/.task"

🌈 Filter configuration

name — the name of the filter
filter — specifies the criteria that must be met for a task to be counted towards this filter
config_override — an array containing configuration overrides, useful for explicitly setting context or other configuration variables. Default: []

🫶 Placeholders

icon — a static icon — type: Icon — unit: -
count — the number of tasks matching current filter — type: Number — unit: -
filter_name — the name of current filter — type: Text — unit: -

🌸 Actions

next_filter — default button: Right

💫 Example

In this example, block will be hidden if count is zero. Iconic behaviour honestly.

[[block]]
block = "taskwarrior"
interval = 60
format = " $icon count.eng(w:1) tasks "
format_singular = " $icon 1 task "
format_everything_done = ""
warning_threshold = 10
critical_threshold = 20
[[block.filters]]
name = "today"
filter = "+PENDING +OVERDUE or +DUETODAY"
[[block.filters]]
name = "some-project"
filter = "project:some-project +PENDING"
config_override = ["rc.context:none"]

🎀 Icons Used

tasks ($icon)

🍓 tea_timer

Timer ⏳

✨ Configuration ✨

Okay so here's the vibe check on the knobs you can turn for this block 🎛️

format — a string to customise the output of this block. See below for available placeholders. Default: " $icon {$time.duration(hms:true)|}"
increment — the numbers of seconds to add each time the block is clicked. Default: 30
done_cmd — a command to run in sh when the timer finishes. Default: None

And the placeholders you can drop into that format string 👇

icon — a static icon — type Icon — unit -
time — the time remaining on the timer — type Duration — unit -
hours — the hours remaining on the timer — type Text — unit h — DEPRECATED
minutes — the minutes remaining on the timer — type Text — unit mn — DEPRECATED
seconds — the seconds remaining on the timer — type Text — unit s — DEPRECATED

fr fr: time, hours, minutes, and seconds are unset when the timer is inactive. So no ghost numbers, bestie — they literally just vanish 👻

Also! hours, minutes, and seconds have been deprecated in favor of time. Use time, she's the main character now 💅

Actions, and which button does what:

increment — Left / Wheel Up
decrement — Wheel Down
reset — Right

🍓 Example 🍓

[[block]]
block = "tea_timer"
format = " $icon {$minutes:$seconds |}"
done_cmd = "notify-send 'Timer Finished'"

🧚 Icons Used 🧚

tea ($icon)

🌡️ temperature 🌡️

The system temperature, coming at you live 🔥 This block displays the system temperature, based on the libsensors library.

This block has two modes: "collapsed", which uses only color as an indicator, and "expanded", which shows the content of a format string. The average, minimum, and maximum temperatures are computed using all sensors displayed by sensors, or optionally filtered by chip and inputs.

Requires libsensors and appropriate kernel modules for your hardware — no cap, check those first 🫶

Run the sensors command to list available chips and inputs. That's your cheat sheet ✨

Heads up! The colour of the block is always determined by the maximum temperature across all sensors, not the average. Keep that in mind if you have a misbehaving sensor — one chaotic little guy can absolutely hijack the whole vibe 😭

🎀 Configuration 🎀

format — a MultiFormat/MaybeMultiFormatConfig string to customise the output of this block. See below for available placeholders. Default: [" $icon $average avg, $max max "]
interval — update interval in seconds. Default: 5
scale — either "celsius" or "fahrenheit". Default: "celsius"
good — maximum temperature to set state to good. Default: 20 °C (68 °F)
idle — maximum temperature to set state to idle. Default: 45 °C (113 °F)
info — maximum temperature to set state to info. Default: 60 °C (140 °F)
warning — maximum temperature to set state to warning. Beyond this temperature, state is set to critical. Default: 80 °C (176 °F)
chip — narrows the results to a given chip name. * may be used as a wildcard. Default: None
inputs — narrows the results to individual inputs reported by each chip. Default: None

Actions:

toggle_format — toggles between format and format_alt. Default button: - — DEPRECATED
next_format — switches to the next format in the list. Default button: Left
prev_format — switches to the previous format in the list. Default button: Right

Placeholders, bestie:

min — minimum temperature among all inputs — type Number — unit Degrees
average — average temperature among all inputs — type Number — unit Degrees
max — maximum temperature among all inputs — type Number — unit Degrees

Note that when the block is collapsed, no placeholders are provided. Zero. None. Empty plate 🍽️

🌈 Example 🌈

[[block]]
block = "temperature"
format = " $icon $max max "
format_alt = " $icon $min min, $max max, $average avg "
interval = 10
chip = "*-isa-*"

🎀 Icons Used 🎀

thermometer ($icon)

⏰ time ⏰

The current time. Yeah that's it. It's giving clock. Iconic 🕰️

💜 Configuration 💜

format — a MultiFormat/MaybeMultiFormatConfig string. See the chrono docs at https://docs.rs/chrono/0.3.0/chrono/format/strftime/index.html#specifiers for all options. Default: [" $icon $timestamp.datetime() "]
interval — update interval in seconds. Default: 10
timezone — a timezone specifier (e.g. "Europe/Lisbon"). Default: Local timezone

Placeholders:

icon — a static icon — type Icon — unit -
timestamp — the current time — type Datetime — unit -

Actions:

next_timezone — default button: Left
prev_timezone — default button: Right
next_format — default button: -
prev_format — default button: -

🌸 Example 🌸

[[block]]
block = "time"
interval = 60
[block.format]
full = " $icon $timestamp.datetime(f:'%a %Y-%m-%d %R %Z', l:fr_BE) "
short = " $icon $timestamp.datetime(f:%R) "

🦋 Non Gregorian calendars 🦋

Okay this is the cool part — you can use calendars other than the Gregorian calendar by adding the calendar specifier in the locale string. But when you use this feature you can't use a chrono style format string, so instead you should use one of the options provided by the icu4x crate: short, medium, long, full. If you set precision to hours/hour/h, minutes/minute/m, or seconds/second/s, then the datetime will be formatted accordingly — otherwise only the date will be displayed.

Only available using feature icu_calendar. 🫶

⭐ Example ⭐

[[block]]
block = "time"
interval = 60
format = "$timestamp.datetime(locale:'fa-IR-u-ca-persian', f:'full', precision: minutes)"

🌟 Icons Used 🌟

time ($icon)

🎚️ toggle 🎚️

A Toggle block. The switch of your dreams ✨

You can add commands to be executed to disable the toggle (command_off), and to enable it (command_on). If these commands exit with a non-zero status, the block will not be toggled, and the block state will be changed to critical to give you a visual warning of the failure — dramatic but honest 💀 You also need to specify a command to determine the state of the toggle (command_state). When the command outputs nothing, the toggle is disabled, otherwise it's enabled. By specifying the interval property you can let the command_state be executed continuously.

To run those commands, the shell form $SHELL environment variable is used. If such variable is not presented, sh is used.

🎀 Configuration 🎀

format — a string to customise the output of this block. See below for available placeholders. Default: " $icon "
command_on — shell command to enable the toggle. Default: Required
command_off — shell command to disable the toggle. Default: Required
command_state — shell command to determine the state. Empty output => No, otherwise => Yes. Default: Required
icon_on — icon override for the toggle button while on. Default: "toggle_on"
icon_off — icon override for the toggle button while off. Default: "toggle_off"
interval — update interval in seconds. If not set, command_state will run only on click. Default: None
state_on — [State] (color) of this block while on. Default: [idle][State::Idle]
state_off — [State] (color) of this block while off. Default: [idle][State::Idle]
icon — Icon based on toggle's state · Icon · no unit (-)

and the action situation is literally just:

toggle — default button: Left

✨ Examples ✨

ok bestie this is the whole thing you'd use to flip between an external monitor setup and your laptop screen, no cap:

[[block]]
block = "toggle"
format = " $icon 4k "
command_state = "xrandr | grep 'DP1 connected 38' | grep -v eDP1"
command_on = "~/.screenlayout/4kmon_default.sh"
command_off = "~/.screenlayout/builtin.sh"
interval = 5
state_on = "good"
state_off = "warning"

🎀 Icons Used 🎀

toggle_off ($icon)
toggle_on ($icon)

⏱️ uptime ⏱️

System's uptime, slay. This block shows your uptime using the two biggest units only — so it's minutes and seconds, or hours and minutes, or days and hours, or weeks and days. That's it, that's the whole vibe.

Configuration

format — a string to customise the output of this block, see below for the placeholders you can use. Default: " $icon $uptime "
interval — update interval in seconds. Default: 60

Placeholders, bestie:

icon — a static icon · Icon · no unit (-)
text DEPRECATED — current uptime · Text · no unit (-)
uptime — current uptime · Duration · no unit (-)

heads up: text has been deprecated in favor of uptime. Use uptime, ok? 🫶

🌸 Example 🌸

[[block]]
block = "uptime"
interval = 3600 # update every hour

🦋 Used Icons 🦋

uptime

🔐 vpn 🔐

Shows the current connection status for VPN networks. And yes — this widget toggles the connection on left click, iconic behaviour honestly.

Configuration

driver — which vpn should be used. Available drivers are: "nordvpn", "mullvad", "tailscale". Default: "nordvpn"
interval — update interval in seconds. Default: 10
format_connected — a string to customise the output in case the network is connected. See below for available placeholders. Default: " VPN: $icon "
format_disconnected — a string to customise the output in case the network is disconnected. See below for available placeholders. Default: " VPN: $icon "
format_connecting — a string to customise the output in case the network is in a connecting state. See below for available placeholders. Default: " VPN: $icon "
state_connected — the widget's state if the vpn network is connected. Default: info
state_disconnected — the widget's state if the vpn network is disconnected. Default: idle

Placeholders 💅:

icon — a static icon · Icon · no unit (-)
country — country currently connected to · Text · no unit (-)
flag — country specific flag (depends on a font supporting them) · Text · no unit (-)
profile — currently selected profile configuration (tailnet) · Text · no unit (-)
error — error message if any · Text · no unit (-)

Actions:

toggle — default button: Left — toggles the vpn network connection

🧚 Drivers 🧚

Mullvad

Behind the scenes the mullvad driver uses the mullvad command line binary. In order for this to work properly the binary should be executable and mullvad daemon should be running.

nordvpn

Behind the scenes the nordvpn driver uses the nordvpn command line binary. In order for this to work properly the binary should be executable without root privileges.

Tailscale

Behind the scenes the tailscale driver uses the tailscale command line binary. In order for this to work properly the tailscale daemon should be running and the user must be configured as operator:

sudo tailscale set --operator=$USER

Cloudflare WARP

Behind the scenes the WARP driver uses the warp-cli command line binary. Just ensure the binary is executable without root privileges.

🌈 Example 🌈

Shows the current vpn network state:

[[block]]
block = "vpn"
driver = "nordvpn"
interval = 10
format_connected = "VPN: $icon "
format_disconnected = "VPN: $icon "
format_connecting = "VPN: $icon "
state_connected = "good"
state_disconnected = "warning"

Possible values for state_connected and state_disconnected, fr fr:

warning
critical
good
info
idle

⭐ Icons Used ⭐

net_vpn ($icon, in format_connected)
net_wired ($icon, in format_disconnected)
net_wireless ($icon, in format_connecting)
net_down ($icon, in format_disconnected, on errors)
country code flags (if supported by font)

Flags: they are not icons but unicode glyphs. You will need a font that includes them. Tested with: https://www.babelstone.co.uk/Fonts/Flags.html

🕵️ watson 🕵️

Watson statistics. Watson is a simple CLI time tracking application. This block will show the name of your current active project, tags and optionally recorded time. Clicking the widget will toggle the show_time variable dynamically — cute, right? 🎀

Configuration

format — a string to customise the output of this block. See below for available placeholders. Default: " $text \|"
show_time — whether to show recorded time. Default: false
state_path — path to the Watson state file. Supports path expansions e.g. ~. Default: $XDG_CONFIG_HOME/watson/state
interval — update interval, in seconds. Default: 60

Placeholders:

text — current activity · Text · no unit (-)

Actions:

toggle_show_time — toggle the value of show_time — default button: Left

💜 Example 💜

[[block]]
block = "watson"
show_time = true
state_path = "~/.config/watson/state"

🍓 TODO 🍓

Extend functionality: start / stop watson using this block

🌤️ weather 🌤️

Current weather. This block displays local weather and temperature information. In order to use this block, you will need access to a supported weather API service. At the time of writing, OpenWeatherMap, met.no, and the US National Weather Service are supported.

Configuring this block requires configuring a weather service, which may require API keys and other parameters.

important: if using the autolocate feature, set the autolocate update interval such that you do not exceed ipapi.co's free daily limit of 1000 hits. Or use autolocate_interval = "once" to only run on initialization.

Configuration

service — the configuration of a weather service (see below). Default: Required
format — a [MultiFormat][MaybeMultiFormatConfig] string to customise the output of this block. See below for available placeholders. Text may need to be escaped, refer to Escaping Text. Default: [" $icon $weather $temp "]
interval — update interval, in seconds. Default: 600
autolocate — gets your location using the ipapi.co IP location service (no API key required). If the API call fails then the block will fallback to service specific location config. Default: false
autolocate_interval — update interval for autolocate in seconds or "once". Default: interval
units — either "metric" (°C, m/s) or "imperial" (°F, mph). If set, will supersede any units setting in the service-specific config. Default: "metric"

🔑 OpenWeatherMap Options 🔑

To use the service you will need a (free) API key.

Okay so the OpenWeatherMap service keys — full rundown, no skips, bestie:

name — literally just openweathermap. — required: Yes, default: None
api_key — Your OpenWeatherMap API key. — required: Yes, default: None
coordinates — GPS latitude longitude coordinates as a tuple, example: ["39.2362","9.3317"] — required: Yes*, default: None
city_id — OpenWeatherMap's ID for the city. (Deprecated) — required: Yes*, default: None
place — OpenWeatherMap `By {city name},{state code},{country code}' search query. See here ⟨https://openweathermap.org/api/geocoding-api#direct_name⟩. Consumes an additional API call — required: Yes*, default: None
zip — OpenWeatherMap `By {zip code},{country code}' search query. See here ⟨https://openweathermap.org/api/geocoding-api#direct_zip⟩. Consumes an additional API call — required: Yes*, default: None
units — either "metric" or "imperial". — required: No, default: "metric"
lang — ⚠️ DEPRECATED. Language code. See here ⟨https://openweathermap.org/current#multi⟩. Currently only affects weather_verbose key. — required: No, default: "en"
forecast_hours — how many hours should be forecast (must be increments of 3 hours, max 120 hours) — required: No, default: 12

One of coordinates, city_id, place, or zip is required. And if you hand over more than one? The precedence is a whole hierarchy, bestie, pay attention: coordinates takes precedence over city_id, which takes precedence over place, which takes precedence over zip. 💅

The options api_key, city_id, place, zip, can be omitted from configuration, in which case they must be provided in the environment variables OPENWEATHERMAP_API_KEY, OPENWEATHERMAP_CITY_ID, OPENWEATHERMAP_PLACE, OPENWEATHERMAP_ZIP. (env var girlies stay winning 🫶)

Forecasts are only fetched if forecast_hours > 0 and the format has keys related to forecast. No format keys, no forecast — that's the deal. ✨

met.no Options

name — metno. — required: Yes, default: None
coordinates — GPS latitude longitude coordinates as a tuple, example: ["39.2362","9.3317"] — required: Required if autolocate = false, default: None
lang — language code: en, nn or nb — required: No, default: en
altitude — meters above sea level of the ground — required: No, default: Approximated by server
forecast_hours — how many hours should be forecast — required: No, default: 12

Met.no does not support location name, but if autolocate is enabled then autolocate's city value is used. (so you still get a name, just borrowed 😌)

US National Weather Service Options

name — nws. — required: Yes, default: None
coordinates — GPS latitude longitude coordinates as a tuple, example: ["39.2362","9.3317"] — required: Required if autolocate = false, default: None
forecast_hours — how many hours should be forecast — required: No, default: 12
units — ⚠️ DEPRECATED. Either "metric" or "imperial". — required: No, default: "metric"

Forecasts gather statistics from each hour between now and the forecast_hours value, and provide predicted weather at the set number of hours into the future. So like, it's doing math for you. Iconic behavior honestly. 🧮

Available Format Keys

location — location name (exact format depends on the service) — type: Text — unit: -
icon{,_ffin} — icon representing the weather — type: Icon — unit: -
weather{,_ffin} — textual brief description of the weather, e.g. "Raining" — type: Text — unit: -
weather_verbose{,_ffin} — textual verbose description of the weather, e.g. "overcast clouds" — type: Text — unit: -
temp{,_{favg,fmin,fmax,ffin}} — temperature (°C or °F, based on units) — type: Number — unit: degrees
apparent{,_{favg,fmin,fmax,ffin}} — Australian Apparent Temperature (°C or °F, based on units) — type: Number — unit: degrees
humidity{,_{favg,fmin,fmax,ffin}} — humidity — type: Number — unit: %
wind{,_{favg,fmin,fmax,ffin}} — wind speed (m/s or mph, based on units) — type: Number — unit: -
wind_kmh{,_{favg,fmin,fmax,ffin}} — wind speed. The wind speed in km/h — type: Number — unit: -
direction{,_{favg,fmin,fmax,ffin}} — wind direction, e.g. "NE" — type: Text — unit: -
sunrise — time of sunrise (may be absent if it's a polar day or polar night)[3] — type: DateTime — unit: -
sunset — time of sunset (may be absent if it's a polar day or polar night)[4] — type: DateTime — unit: -

You can use the suffixes noted above to get the following:

None — current weather
_favg — average forecast value
_fmin — minimum forecast value
_fmax — maximum forecast value
_ffin — final forecast value

Now the click actions, bestie — these are how you make it do stuff:

toggle_format — toggles between format and format_alt — ⚠️ DEPRECATED — default button: -
next_format — switches to the next format in the list — default button: Left
prev_format — switches to the previous format in the list — default button: Right

Examples

Show detailed weather in San Francisco through the OpenWeatherMap service:

[[block]]
block = "weather"
format = " $icon $weather ($location) $temp, $wind m/s $direction "
format_alt = " $icon_ffin Forecast (9 hour avg) {$temp_favg ({$temp_fmin}-{$temp_fmax})|Unavailable} "
[block.service]
name = "openweathermap"
api_key = "XXX"
city_id = "5398563"
units = "metric"
forecast_hours = 9

Show sunrise and sunset times in null island:

[[block]]
block = "weather"
format = "up $sunrise.datetime(f:'%R') down $sunset.datetime(f:'%R')"
[block.service]
name = "metno"
coordinates = ["0", "0"]

Used Icons

weather_sun ($icon $icon_ffin, when weather is reported as "Clear" during the day)
weather_moon ($icon $icon_ffin, when weather is reported as "Clear" at night)
weather_clouds ($icon $icon_ffin, when weather is reported as "Clouds" during the day)
weather_clouds_night ($icon $icon_ffin, when weather is reported as "Clouds" at night)
weather_fog ($icon $icon_ffin, when weather is reported as "Fog" or "Mist" during the day)
weather_fog_night ($icon $icon_ffin, when weather is reported as "Fog" or "Mist" at night)
weather_rain ($icon $icon_ffin, when weather is reported as "Rain" or "Drizzle" during the day)
weather_rain_night ($icon $icon_ffin, when weather is reported as "Rain" or "Drizzle" at night)
weather_snow ($icon $icon_ffin, when weather is reported as "Snow")
weather_thunder ($icon $icon_ffin, when weather is reported as "Thunderstorm" during the day)
weather_thunder_night ($icon $icon_ffin, when weather is reported as "Thunderstorm" at night)
weather_default ($icon $icon_ffin, in all other cases)

xrandr

X11 screen information 🌈

X11 screen information (name, brightness, resolution, refresh rate). With a click you can toggle through your active screens, and scrolling the wheel up/down, you can adjust the selected screens' brightness. Regarding brightness control, xrandr changes the brightness of the display using gamma rather than changing the brightness in hardware, so if that is not desirable, then consider using the backlight block instead. 💡

NOTE: Some users report issues (e.g. here and here) when using this block. The cause is currently unknown, however, setting a higher update interval may help. 😭 No cap, if it's acting up, crank that interval.

⚙️ Configuration ⚙️

Okay bestie, here's the little settings menu for this block — every knob, every default, no crumbs left behind 💅

format — a string that customises the output of this block. Peek below for the available placeholders. Default: " $icon $display $brightness_icon $brightness "
step_width — how many steps the brightness goes up/down by for the selected screen (if you set it greater than 50, it gets limited to 50, no cap-fighting the cap). Default: 5
interval — update interval in seconds. Default: 5
invert_icons — flips the ordering of the icons, which is super useful if you're rocking colourful emoji. Default: false

✨ Placeholders ✨ — here's what you can drop into your format string:

icon — a static icon. Type: Icon. Unit: -
display — the monitor name. Type: Text. Unit: -
brightness — the monitor brightness. Type: Number. Unit: %
brightness_icon — a static icon. Type: Icon. Unit: -
resolution — the monitor resolution. Type: Text. Unit: -
res_icon — a static icon. Type: Icon. Unit: -
refresh_rate — the monitor refresh rate. Type: Number. Unit: Hertz

🎮 Actions & their default buttons 🎮 — clicky clicky:

cycle_outputs — Left
brightness_up — Wheel Up
brightness_down — Wheel Down

🌸 Example 🌸

Steal this, it's cute:

[[block]]
block = "xrandr"
format = " $icon $brightness $resolution $refresh_rate "

🎀 Used Icons 🎀

The icons this block pulls from, bestie:

xrandr
backlight
resolution

📌 NOTES 📌

The footnotes, but make them glamorous:

[1] when using notification_count with the dunst driver use dunst > 1.9.0 — yes, that's a version gate, respect it 😤

[2] history_count is the same as notification_count in SwayNC — twins fr fr

[3] On polar days and polar nights, sunrise or sunset may not occur on a given day, and thus the corresponding value may be absent. This behaviour depends on the weather service used. For met.no and nws, both sunrise and sunset will be absent on polar days and polar nights, but OpenWeatherMap will show the same time for both sunrise and sunset.

[4] On polar days and polar nights, sunrise or sunset may not occur on a given day, and thus the corresponding value may be absent. This behaviour depends on the weather service used. For met.no and nws, both sunrise and sunset will be absent on polar days and polar nights, but OpenWeatherMap will show the same time for both sunrise and sunset.

Yes bestie, [3] and [4] are literally the same note twice. Not a typo on my end — the manpage said it twice, so I'm saying it twice. Consistency icon 👑

🌈 THEMES 🌈

Choosing your theme and icon set

Want a theme or icon set that isn't the default? Same, honestly. Drop them into your config file like so:

[theme]
theme = "solarized-dark"
[icons]
icons = "awesome6"

Plot twist: both the theme and the icon set can be loaded from a separate file 🦋

[theme]
theme = "<file>"
[icons]
icons = "<file>"

Where <file> can be either a filename or a full path — and it gets checked in this exact order:

If a full absolute path is given, then use it as is: /home/foo/custom_theme.toml
If a filename is given, e.g. "custom_theme.toml", then first check $XDG_CONFIG_HOME/i3status-rust/themes
Then look for it in $XDG_DATA_HOME/i3status-rust/themes
Otherwise look for it in /usr/share/i3status-rust/themes

Notes, and I'm reading these to you verbatim because they matter:

In case with icon sets, the file should be in the icons subdirectory instead of themes.
You can omit the .toml extension while specifying file parameters.
All the predefined themes are provided as files, so you use them as examples of how to write your own themes/icon sets.

Available themes

Note: screenshots were generated using this config with this swaybar config.

The lineup, and yes I'm listing every single one 💖

plain (default) [IMAGE: plain]
solarized-dark [IMAGE: solarized-dark]
solarized-light [IMAGE: solarized-light]
slick [IMAGE: slick]
modern [IMAGE: modern]
bad-wolf [IMAGE: bad-wolf]
gruvbox-light [IMAGE: gruvbox-light]
gruvbox-dark [IMAGE: gruvbox-dark]
space-villain [IMAGE: space-villain]
native (like plain with no background and native separators) [IMAGE: native]
semi-native (like native but with background) [IMAGE: semi-native]
nord-dark (polar night) [IMAGE: nord-dark]
dracula [IMAGE: dracula]
srcery [IMAGE: srcery]
ctp-frappe [IMAGE: ctp-frappe]
ctp-latte [IMAGE: ctp-latte]
ctp-macchiato [IMAGE: ctp-macchiato]
ctp-mocha [IMAGE: ctp-mocha]
tomorrow-night [IMAGE: tomorrow-night]

Available icon sets

none (default. Uses text labels instead of icons)
awesome4 (Font Awesome 4.x)
awesome5 (Font Awesome 5.x)
awesome6 (Font Awesome 6.x)
awesome7 (Font Awesome 7.x)
awesome7pro (Font Awesome 7.x Pro)
emoji
material
material-nf (Any font from Nerd Fonts collection)

Note: In order to use the material icon set, you need a patched material icons font which can be found here. Make sure to pass it in your i3 configuration bar block. Don't skip this step, or you'll get sad little boxes 😭

Overriding themes and icon sets

Make a block in the configuration called theme or icons, like so:

[theme]
theme = "solarized-dark"
[theme.overrides]
# Example: redefine `idle` colors
idle_bg = "#123456"
idle_fg = "#abcdef"
# Example: swap `good` and `warning` colors
good_fg = { link = "warning_fg" }
good_bg = { link = "warning_bg" }
warning_fg = { link = "good_fg" }
warning_bg = { link = "good_bg" }

[icons]
icons = "awesome6"
[icons.overrides]
bat = [
    "| |",
    "|¼|",
    "|½|",
    "|¾|",
    "|X|",
]
bat_charging = "|^|"

Besides global overrides, you may also use per-block overrides using the theme_overrides, icons_overrides and icons_format options available for all blocks. For example:

[[block]]
block = "cpu"
icons_format = "{icon}"
[block.theme_overrides]
idle_bg = "#123456"
idle_fg = "#abcdef"
[block.icons_overrides]
cpu_boost_on = "ON"
cpu_boost_off = "OFF"

If you define colors in ~/.Xresources like *background: #aabbcc you can use them like:

[theme]
theme = "solarized-dark"
[theme.overrides]
# Example: redefine `idle_bg` with the background color
idle_bg = "x:background"

And if you use sway, you can also reference a bar color like:

[theme]
theme = "solarized-dark"
[theme.overrides]
# Example: redefine `critical` colors
critical_bg = "sway:urgent_workspace_bg"
critical_fg = "sway:urgent_workspace_text"

These are the available sway colors — the whole squad 👑

active_workspace_bg
active_workspace_border
active_workspace_text
background
binding_mode_bg
binding_mode_border
binding_mode_text
focused_background
focused_separator
focused_statusline
focused_workspace_bg
focused_workspace_border
focused_workspace_text
inactive_workspace_bg
inactive_workspace_border
inactive_workspace_text
separator
statusline
urgent_workspace_bg
urgent_workspace_border
urgent_workspace_text

You can see the current values for your bar with swaymsg -t get_bar_config <bar-name>.

Available theme overrides

All bg and fg overrides are either:

html hex color codes like #000000 or #789ABC; a fourth byte for alpha (like #acbdef42) works on some systems. 00 is transparent, FF is opaque, or
a reference to another override, e.g., { link = "idle-bg" }, or
a reference to a color name defined in ~/.Xresources, e.g., x:background looks for a line like *background: #aabbcc in ~/.Xresources (see also .Xresources).

The tints are added to every second block counting from the right. They will therefore always brighten the block and never darken it. The alpha channel, if it works, can also be alternated in the same way.

Feel free to take a look at the provided color schemes for reference 💅

idle_bg
idle_fg
good_bg
good_fg
warning_bg
warning_fg
critical_bg
critical_fg
info_bg
info_fg
alternating_tint_bg
alternating_tint_fg
separator_bg
separator_fg
separator
end_separator
start_separator

Available icon overrides

These can be directly set to a string containing the desired unicode codepoint(s) or use a TOML escape sequence like "\uf0f3" for up to 4-nibble codepoints and "\U0001f312" for up to 8-nibble codepoints.

You can find the codepoints in the documentation of the icon font you're using — go hunt them down, it's lowkey fun 🧚

Refer to individual block's documentation for a list of used icons or provided icon sets for a complete list of icons.

🦋 VERSION 🦋

v0.36.2 (commit )

👑 AUTHORS 👑

Kai Greshake <development@kai-greshake.de>, Contributors on GitHub (https, //github.com/greshake/i3status-rust/graphs/contributors)

And that's the whole page, bestie — every last crumb 🍓

<i3status-rs 0.36.2 (commit ) — i3status-rs(1)</i3status-rs> — okay that tag was a bit much, but the footer really does say: i3status-rs 0.36.2 (commit ) on the left and i3status-rs(1) on the right. Slay, go configure your bar 💜✨

📦 where this page comes from

arch rolling: i3status-rust 0.36.2-1 · GPL-3.0-only
nixpkgs unstable: i3status-rust 0.36.2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms