i3status-rs(1)

amd_gpu

Display the stats of your AMD GPU

Configuration

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⟩\c

Configuration

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⟩\c 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

time has been deprecated in favor of time_remaining.

Examples

Basic usage:

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

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

Hide missing battery:

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

Icons Used

•

bat ($icon, in format full_format empty_format not_charging_format, as a progression)

•

bat_charging ($icon, in charging_format, as a progression)

•

bat_not_available ($icon, in missing_format)

bluetooth

Monitor Bluetooth device

This block displays the connectivity of a given Bluetooth device and the battery level if this is supported. Relies on the Bluez D-Bus API.

When the device can be identified as an audio headset, a keyboard, joystick, or mouse, use the relevant icon. Otherwise, fall back on the generic Bluetooth symbol.

Right-clicking the block will attempt to connect (or disconnect) the device.

Note: battery level information is not reported for some devices.Enabling experimental features of bluez ⟨https://wiki.archlinux.org/title/bluetooth#Enabling_experimental_features⟩\c may fix it.

Configuration

Examples

This example just shows the icon when 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 ($icon) for bluetooth devices identifying as “audio-card”, “audio-headset” or “audio-headphones”

•

joystick ($icon) for bluetooth devices identifying as “input-gaming”

•

keyboard ($icon) for bluetooth devices identifying as “input-keyboard”

•

mouse ($icon) for bluetooth devices identifying as “input-mouse”

•

bluetooth ($icon) for all other devices, and when the device is unavailable

•

bat ($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.

Configuration

Source Configuration

Note: Currently only one source is supported

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 configure 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 access the CalDav API of Google, follow these steps to enable the API and obtain the client_id and client_secret: 1. Go to the Google Cloud Console: Navigate to the Google Cloud Console ⟨https://console.cloud.google.com/⟩\c . 2. 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”. 3. 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”. 4. Set Up OAuth Consent Screen: Go to “APIs & Services” > “OAuth consent screen”. Fill out the required information and save. 5. 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. 6. 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 configure the 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 a string that can include placeholders to be replaced with dynamic content. Placeholders can be: - $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

CPU statistics

Configuration

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

The output of a custom shell command

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) short_text is optional.

Configuration

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

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

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

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

Configuration

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

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 block on right click:

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

Show the block only if less than 10GB is available:

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

Icons Used

•

disk_drive ($icon)

docker

Local docker daemon status

Configuration

Examples

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

This example allows showing Podman status by setting the socket path (path is dependent on your own setup).

[[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

External IP address and various information about it

Configuration

Example

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

Notes

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

The IP is queried, 1) When i3status-rs starts, 2) When a signal is received on D-Bus about a network configuration change, 3) Every 5 minutes. This periodic refresh exists to catch IP updates that don’t trigger a notification, for example due to a IP refresh at the router.

If the service reports rate limiting, the block keeps showing the last known IP and waits for the geolocator’s rate_limit_interval (10 minutes by default) before asking again.

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⟩\c

focused_window

Currently focused window

This block displays the title and/or the active marks (when used with sway/i3) of the currently focused window. Supported WMs are: sway, i3 and most wlroots-based compositors. See driver option for more info.

Configuration

Example

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

This example instead of hiding block when the window’s title is empty 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. A GitHub personal access token ⟨https://github.com/settings/tokens/new⟩\c with the “notifications” scope is required, and must be passed using the I3RS_GITHUB_TOKEN environment variable or token configuration option. Optionally the colour of the block is determined by the highest notification in the following lists from highest to lowest: critical,warning,info,good

Configuration

All the placeholders are numbers without a unit.

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 scrolling upon the block the color temperature is changed. A left click on the block sets the color temperature to click_temp that is by default to 6500K. A right click completely resets the color temperature to its default value (6500K).

Configuration

Available Hue Shifters

Note that at the moment, only wl_gammarelay ⟨https://github.com/jeremija/wl-gammarelay⟩\c and wl_gammarelay_rs ⟨https://github.com/MaxVerevkin/wl-gammarelay-rs⟩\c subscribe to the events and update the bar when the temperature is modified externally. Also, these are the only drivers at the moment that work under Wayland without flickering.

Example

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

A hard limit is set for the max_temp to 10000K and the same for the min_temp which is 1000K. The step has a hard limit as well, defined to 500K to avoid too brutal changes.

kdeconnect

KDEConnect ⟨https://community.kde.org/KDEConnect⟩\c indicator

Display info from the currently connected device in KDEConnect, updated asynchronously.

Block colours are updated based on the battery level, unless all bat_* thresholds are set to 0, in which case the block colours will depend on the notification count instead.

Configuration

Example

Do not show the name, do 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

Six drivers are 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 ⟨https://github.com/qnikst/kbdd⟩\c 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.

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

Configuration

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

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

Configuration

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.

Note that you need to enable maildir feature to use this block:

cargo build --release --features maildir

Configuration

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

Configuration

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)

menu

A custom menu

This block allows you to 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

Example

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

music

The current song title and artist

Also provides buttons for play/pause, previous and next.

Supports all music players that implement the MediaPlayer2 Interface ⟨https://specifications.freedesktop.org/mpris-spec/latest/Player_Interface.html⟩\c . This includes:

•

Spotify

•

VLC

•

mpd (via mpDris2 ⟨https://github.com/eonpatapon/mpDris2⟩\c )

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

Note: All placeholders except icon can be absent. See the examples below to learn how to handle this.

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 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 displays with rotating text

[[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

This block uses sysfs and netlink and thus does not require any external dependencies.

Configuration

Example

Display WiFi info if available

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

Display exact device

[[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

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

Configuration

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

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

Note that you need to enable notmuch feature to use this block:

cargo build --release --features notmuch

Configuration

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

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.

Configuration

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.

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

Apt

Behind the scenes this uses apt, and in order to run it without root privileges i3status-rust will create its own package database in /tmp/i3rs-apt/ which may take up several MB or more. If you have a custom apt config then this block may not work as expected - in that case please open an issue.

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).

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 ⟨https://github.com/actionless/pikaur/issues/595⟩\c . In that case, try a different AUR helper.

Pacman hook

Tip: On Arch Linux you can setup a pacman hook to signal i3status-rs to update after packages have been upgraded, so you won’t have stale info in your pacman block.

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:'"

Multiple package managers config:

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 ⟨https://en.wikipedia.org/wiki/Pomodoro_Technique⟩\c

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.

Configuration

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

Configuration

pipewire Options (requires the pipewire feature to be enabled)

vl4 Options

Available Format Keys

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

Available Actions

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 in rofication-daemon

A different color is used if there are critical notifications.

Configuration

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

Configuration

Example

[[block]]
block = "scratchpad"

Icons Used

•

scratchpad ($icon)

service_status

Display the status of a service

Right now only systemd is supported.

Configuration

Example

Example using an icon:

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

Example overriding the default inactive_state:

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

sound

Volume level

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

Requires a PulseAudio installation or alsa-utils for ALSA.

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%.

Configuration

Examples

Change the default scrolling step width to 3 percent:

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

Change the output name shown:

[[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:

[[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 ⟨https://github.com/cloudflare/networkquality-rs⟩\c (nq) library to run a speedtest and report the ping, jitter, download speed, and upload speed.

The block can be configured to use custom endpoints for the speedtest, but by default Cloudflare’s nq endpoints are used.

For example setting config_url to "https://mensura.cdn-apple.com/.well-known/nq" will use Apple’s nq endpoints instead of Cloudflare’s.

nq is based on the IETF draft: “Responsiveness under Working Conditions” ⟨https://datatracker.ietf.org/doc/draft-ietf-ippm-responsiveness/⟩\c .

The draft defines “responsiveness”, measured in Round trips Per Minute (RPM), as a useful measurement of network quality.

Configuration

Latency Configuration (settings used for ping and jitter)

RPM Configuration (settings used for speed_down and speed_up)

Available Format Keys

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

Clicking the right mouse button on the icon cycles the view of the block through the user’s filters.

Configuration

Filter configuration

Placeholders

Actions

Example

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

[[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

time, hours, minutes, and seconds are unset when the timer is inactive.

hours, minutes, and seconds have been deprecated in favor of time.

Example

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

Icons Used

•

tea ($icon)

temperature

The system temperature

This block displays the system temperature, based on 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.

Run sensors command to list available chips and inputs.

Note that the colour of the block is always determined by the maximum temperature across all sensors, not the average. You may need to keep this in mind if you have a misbehaving sensor.

Configuration

Note that when block is collapsed, no placeholders are provided.

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.

Configuration

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

You can use calendars other than the Gregorian calendar by adding the calendar specifier in the locale string. When using this feature you can’t use chrono style format string, and 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 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

You can add commands to be executed to disable the toggle (command_off), and to enable it (command_on). If these command exit with a non-zero status, the block will not be toggled and the block state will be changed to critical to give a visual warning of the failure. 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 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

Examples

This is what can be used to toggle an external monitor configuration:

[[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

This block displays system uptime in terms of two biggest units, so minutes and seconds, or hours and minutes or days and hours or weeks and days.

Configuration

text has been deprecated in favor of uptime.

Example

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

Used Icons

•

uptime

vpn

Shows the current connection status for VPN networks

This widget toggles the connection on left click.

Configuration

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:

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⟩\c

watson

Watson statistics

Watson ⟨http://tailordev.github.io/Watson/⟩\c 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.

Configuration

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.

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

OpenWeatherMap Options

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

One of coordinates, city_id, place, or zip is required. If more than one are supplied, 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.

Forecasts are only fetched if forecast_hours > 0 and the format has keys related to forecast.

met.no Options

Met.no does not support location name, but if autolocate is enabled then autolocate’s city value is used.

US National Weather Service Options

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.

Available Format Keys

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

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 ⟨https://github.com/greshake/i3status-rust/issues/274⟩\c and here ⟨https://github.com/greshake/i3status-rust/issues/668⟩\c when using this block. The cause is currently unknown, however, setting a higher update interval may help.

Configuration

Example

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

Used Icons

•

xrandr

•

backlight

•

resolution

[1]

when using notification_count with the dunst driver use dunst > 1.9.0

[2]

history_count is the same as notification_count in SwayNC

[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.

Choosing your theme and icon set

To use a theme or icon set other than the default, add them to your configuration file like so:

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

Both the theme and 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 will be checked in this order:

1.

If full absolute path given, then use it as is: /home/foo/custom_theme.toml

2.

If filename given, e.g. “custom_theme.toml”, then first check $XDG_CONFIG_HOME/i3status-rust/themes

3.

Then look for it in $XDG_DATA_HOME/i3status-rust/themes

4.

Otherwise look for it in /usr/share/i3status-rust/themes

Notes: - 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.

•

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 ⟨https://gist.github.com/draoncc/3c20d8d4262892ccd2e227eefeafa8ef/raw/3e6e12c213fba1ec28aaa26430c3606874754c30/MaterialIcons-Regular-for-inline.ttf⟩\c . Make sure to pass it in your i3 configuration bar block.

Overriding themes and icon sets

Create 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"

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:

•

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 ⟨https://wiki.debian.org/Xresources⟩\c ).

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.

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