I3STATUS-RS(1)

NAME
i3status-rs - Generates a status line for i3bar(1)-compatible bars

SYNOPSIS
i3status-rs [OPTIONS] [CONFIGFILE]

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

OPTIONS

-h, --help
    Print help message and exit.

-V, --version
    Print version information and exit.

--never-pause
    Ignore any attempts by i3 to pause the bar when hidden/fullscreen

--exit-on-error
    Exit rather than printing errors to the bar and continuing. Useful for debugging in the console.

CONFIGFILE
    Read the configuration from this file. Otherwise, we fall back on $XDG_CONFIG_HOME/i3status-rust/config.toml.

CONFIGURATION
i3status-rs uses a TOML-based format for specifying an array of “blocks”. There are also a small number of top-level theme and icon settings. A simple configuration might look as follows:

      theme = "solarized-dark"
      icons = "awesome"
      [[block]]
      block = "cpu"
      interval = 1
      [[block]]
      block = "load"
      interval = 1
      format = "{1m}"
      [[block]]
      block = "sound"

For available blocks, see BLOCKS. For theme and icon configuration, see THEMES.

BLOCKS

  apt

Pending updates available for your Debian/Ubuntu based system

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

  Configuration

Key | Values | Default
interval | Update interval in seconds. | 600
format | A string to customise the output of this block. See below for available placeholders. | " $icon $count.eng(w:1) "
format_singular | Same as format, but for when exactly one update is available. | " $icon $count.eng(w:1) "
format_up_to_date | Same as format, but for when no updates are available. | " $icon $count.eng(w:1) "
warning_updates_regex | Display block as warning if updates matching regex are available. | None
critical_updates_regex | Display block as critical if updates matching regex are available. | None
ignore_phased_updates | Doesn’t include potentially held back phased updates in the count. | false

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
count | Number of updates available | Number | -

  Example

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

    [[block]]
    block = "apt"
    interval = 1800
    format = " $icon $count updates available "
    format_singular = " $icon One update available "
    format_up_to_date = " $icon system up to date "
    critical_updates_regex = "(linux|linux-lts|linux-zen)"
    [[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

  Icons Used

•   update

  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.

  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

Key | Values | Default
device | The /sys/class/backlight device to read brightness information from. When there is no device specified, this block will display information from the first device found in the /sys/class/backlight directory. If you only have one display, this approach should find it correctly. | Default device
format | A string to customise the output of this block. See below for available placeholders. | " $icon $brightness "
step_width | The brightness increment to use when scrolling, in percent | 5
minimum | The minimum brightness that can be scrolled down to | 5
maximum | The maximum brightness that can be scrolled up to | 100
cycle | The brightnesses to cycle through on each click | [minimum, maximum]
root_scaling | Scaling exponent reciprocal (ie. root) | 1.0
invert_icons | Invert icons’ ordering, useful if you have colorful emoji | false

Placeholder | Value | Type | Unit
icon | Icon based on backlight’s state | Icon | -
brightness | Current brightness | Number | %

Action | Default button
cycle | Left
brightness_up | Wheel Up
brightness_down | Wheel Down

  Example

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

  Icons Used

•   backlight (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

Key | Values | Default
device | sysfs/UPower: The device in /sys/class/power_supply/ to read from (can also be “DisplayDevice” for UPower). apc_ups: IPv4Address:port or hostname:port | sysfs: the first battery device found in /sys/class/power_supply, with “BATx” or “CMBx” entries taking precedence. apc_ups: “localhost:3551”. upower: DisplayDevice
driver | One of "sysfs", "apc_ups", or "upower" | "sysfs"
interval | Update interval, in seconds. Only relevant for driver = "sysfs" || “apc_ups”. |10format| A string to customise the output of this block. See below for available placeholders. |” $icon $percentage “full_format| Same asformatbut for when the battery is full |” $icon “empty_format| Same asformatbut for when the battery is empty |” $icon “not_charging_format| Same asformatbut for when the battery is not charging. Defaults to the full battery icon as many batteries report this status when they are full. |” $icon “missing_format| Same asformatif the battery cannot be found. |” $icon “info| Minimum battery level, where state is set to info |60good| Minimum battery level, where state is set to good |60warning| Minimum battery level, where state is set to warning |30critical| Minimum battery level, where state is set to critical |15full_threshold| Percentage above which the battery is considered full (full_formatshown) |95empty_threshold| Percentage below which the battery is considered empty |7.5` |

Placeholder | Value | Type | Unit
icon | Icon based on battery’s state | Icon | -
percentage | Battery level, in percent | Number | Percents
time | Time remaining until (dis)charge is complete. Presented only if battery’s status is (dis)charging. | String | -
power | Power consumption by the battery or from the power supply when charging | String or Float | Watts

  Examples

Basic usage:

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

    [[block]]
    block = "battery"
    format = " $percentage {$time |}"
    device = "DisplayDevice"
    driver = "upower"

Hide missing battery:

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

  Icons Used

•   bat (as a progression)

•   bat_charging (as a progression)

•   bat_not_available

  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) may fix it.

  Configuration

Key | Values | Default
mac | MAC address of the Bluetooth device | Required
adapter_mac | MAC Address of the Bluetooth adapter (in case your device was connected to multiple currently available adapters) | None
format | A string to customise the output of this block. See below for available placeholders. | ” $icon $name{ $percentage|} “
disconnected_format | A string to customise the output of this block. See below for available placeholders. | ” $icon{ $name|} “

Placeholder | Value | Type | Unit
icon | Icon based on what type of device is connected | Icon | -
name | Device’s name | Text | -
percentage | Device’s battery level (may be absent if the device is not supported) | Number | %
available | Present if the device is available | Flag | -

Action | Default button
toggle | Right

  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 "

  Icons Used

•   headphones for bluetooth devices identifying as “audio-card”, “audio-headset” or “audio-headphones”

•   joystick for bluetooth devices identifying as “input-gaming”

•   keyboard for bluetooth devices identifying as “input-keyboard”

•   mouse for bluetooth devices identifying as “input-mouse”

•   bluetooth for all other devices

  cpu

CPU statistics

  Configuration

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders. | " $icon $utilization "
format_alt | If set, block will switch between format and format_alt on every click | None
interval | Update interval in seconds | 5

Placeholder | Value | Type | Unit
icon | An icon | Icon | -
utilization | Average CPU utilization | Number | %
utilization<N> | Utilization of Nth logical CPU | Number | %
barchart | Utilization of all logical CPUs presented as a barchart | Text | -
frequency | Average CPU frequency | Number | Hz
frequency<N> | Frequency of Nth logical CPU | Number | Hz
max_frequency | Max frequency of all logical CPUs | Number | Hz
boost | CPU turbo boost status (may be absent if CPU is not supported) | Text | -

Action | Description | Default button
toggle_format | Toggles between format and format_alt | Left

  Example

    [[block]]
    block = "cpu"
    interval = 1
    format = " $icon $barchart $utilization "
    format_alt = " $icon $frequency{ $boost|} "

  Icons Used

•   cpu (as a progression)

•   cpu_boost_on

•   cpu_boost_off

  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

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

Placeholder | Value | Type | Unit
icon | Value of icon field from JSON output when it’s non-empty | Icon | -
text | Output of the script or text field from JSON output | Text |
short_text | short_text field from JSON output | Text |

Action | Default button
cycle | 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 <command> when block is clicked:

    [[block]]
    block = "custom"
    cycle = ["echo ON", "echo OFF"]
    interval = 1
    [[block.click]]
    button = "left"
    cmd = "<command>"

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

Key | Values | Default
format | A string to customise the output of this block. | “{ $icon|}{ $text.str(pango:true)|}”

Placeholder | Value | Type | Unit
icon | Value of icon set via SetIcon if the value is non-empty string. | Icon | -
text | Value of the first string from SetText | Text | -
short_text | Value of the second string from SetText | 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

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_space

Disk usage statistics

  Configuration

Key | Values | Default
path | Path to collect information from. Supports path expansions e.g. ~. | "/"
interval | Update time in seconds | 20
format | A string to customise the output of this block. See below for available placeholders. | " $icon $available "
format_alt | If set, block will switch between format and format_alt on every click | None
warning | A value which will trigger warning block state | 20.0
alert | A value which will trigger critical block state | 10.0
info_type | Determines which information will affect the block state. Possible values are "available", "free" and "used" | "available"
alert_unit | The unit of alert and warning options. If not set, percents are used. Possible values are "B", "KB", "MB", "GB" and "TB" | None

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
path | The value of path option | Text | -
percentage | Free or used percentage. Depends on info_type | Number | %
total | Total disk space | Number | Bytes
used | Used disk space | Number | Bytes
free | Free disk space | Number | Bytes
available | Available disk space (free disk space minus reserved system space) | Number | Bytes

Action | Description | Default button
toggle_format | Toggles between format and format_alt | Left

  Example

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

  Icons Used

•   disk_drive

  dnf

Pending updates available for your Fedora system

  Configuration

Key | Values | Default
interval | Update interval in seconds. | 600
format | A string to customise the output of this block. See below for available placeholders. | " $icon $count.eng(w:1) "
format_singular | Same as format, but for when exactly one update is available. | " $icon $count.eng(w:1) "
format_up_to_date | Same as format, but for when no updates are available. | " $icon $count.eng(w:1) "
warning_updates_regex | Display block as warning if updates matching regex are available. | None
critical_updates_regex | Display block as critical if updates matching regex are available. | None

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
count | Number of updates available | Number | -

  Example

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

    [[block]]
    block = "dnf"
    interval = 1800
    format = " $icon $count.eng(w:1) updates available "
    format_singular = " $icon One update available "
    format_up_to_date = " $icon system up to date "
    critical_updates_regex = "(linux|linux-lts|linux-zen)"
    [[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"

  Icons Used

•   update

  docker

Local docker daemon status

  Configuration

Key | Values | Default
interval | Update interval, in seconds. | 5
format | A string to customise the output of this block. See below for available placeholders. | " $icon $running.eng(w:1) "
socket_path | The path to the docker socket. Supports path expansions e.g. ~. | "/var/run/docker.sock"

Key | Value | Type | Unit
icon | A static icon | Icon | -
total | Total containers on the host | Number | -
running | Containers running on the host | Number | -
stopped | Containers stopped on the host | Number | -
paused | Containers paused on the host | Number | -
images | Total images on the host | Number | -

  Example

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

  Icons Used

•   docker

  external_ip

External IP address and various information about it

  Configuration

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders. | " $ip $country_flag "
interval | Interval in seconds for automatic updates | 300
with_network_manager | If `true', listen for NetworkManager events and update the IP immediately if there was a change | true

Key | Value | Type | Unit
ip | The external IP address, as seen from a remote server | Text | -
version | IPv4 or IPv6 | Text | -
city | City name, such as “San Francisco” | Text | -
region | Region name, such as “California” | Text | -
region_code | Region code, such as “CA” for California | Text | -
country | Country code (2 letter, ISO 3166-1 alpha-2) | Text | -
country_name | Short country name | Text | -
country_code | Country code (2 letter, ISO 3166-1 alpha-2) | Text | -
country_code_iso3 | Country code (3 letter, ISO 3166-1 alpha-3) | Text | -
country_capital | Capital of the country | Text | -
country_tld | Country specific TLD (top-level domain) | Text | -
continent_code | Continent code | Text | -
in_eu | Region code, such as “CA” | Flag | -
postal | ZIP / Postal code | Text | -
latitude | Latitude | Number | - (TODO: make degrees?)
longitude | Longitude | Number | - (TODO: make degrees?)
timezone | City | Text | -
utc_offset | UTC offset (with daylight saving time) as +HHMM or -HHMM (HH is hours, MM is minutes) | Text | -
country_calling_code | Country calling code (dial in code, comma separated) | Text | -
currency | Currency code (ISO 4217) | Text | -
currency_name | Currency name | Text | -
languages | Languages spoken (comma separated 2 or 3 letter ISO 639 code with optional hyphen separated country suffix) | Text | -
country_area | Area of the country (in sq km) | Number | -
country_population | Population of the country | Number | -
timezone | Time zone | Text | -
org | Organization | Text | -
asn | Autonomous system (AS) | Text | -
country_flag | Flag of the country | Text (glyph) | -

  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>

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.

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>

  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

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders. | ” $title.str(max_w:21) |“
driver | Which driver to use. 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. | "auto"

Placeholder | Value | Type | Unit
title | Window’s title (may be absent) | Text | -
marks | Window’s marks (present only with sway/i3) | Text | -
visible_marks | Window’s marks that do not start with _ (present only with sway/i3) | Text | -

  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) 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
    Key | Values | Default
    ----|--------|--------
    `format` | A string to customise the output of this block. See below for available placeholders. | `" $icon $total.eng(w:1) "`
    `interval` | Update interval in seconds | `30`
    `token` | A GitHub personal access token with the "notifications" scope | `None`
    `hide_if_total_is_zero` | Hide this block if the total count of notifications is zero | `false`
    `critical` | List of notification types that change the block to the critical colour | `None`
    `warning` | List of notification types that change the block to the warning colour | `None`
    `info` | List of notification types that change the block to the info colour | `None`
    `good` | List of notification types that change the block to the good colour | `None`
    All the placeholders are numbers without a unit.
    Placeholder        | Value
    -------------------|------
    `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
    ```toml
    [[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

  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

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

Placeholder | Value | Type | Unit
temperature | Current temperature | Number | -

Action | Default button
set_click_temp | Left
reset | Right
temperature_up | Wheel Up
temperature_down | Wheel Down

  Available Hue Shifters

Name | Supports
"redshift" | X11
"sct" | X11
"gammastep" | X11 and Wayland
"wl_gammarelay" | Wayland
"wl_gammarelay_rs" | Wayland
"wlsunset" | Wayland

Note that at the moment, only wl_gammarelay (https://github.com/jeremija/wl-gammarelay) and wl_gammarelay_rs (https://github.com/MaxVerevkin/wl-gammarelay-rs) 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) 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

Key | Values | Default
device_id | Device ID as per the output of kdeconnect --list-devices. | Chooses the first found device, if any.
format | A string to customise the output of this block. See below for available placeholders. | ” $icon $name{ $bat_icon $bat_charge|}{ $notif_icon|} “
bat_info | Min battery level below which state is set to info. | 60
bat_good | Min battery level below which state is set to good. | 60
bat_warning | Min battery level below which state is set to warning. | 30
bat_critical | Min battery level below which state is set to critical. | 15
hide_disconnected | Whether to hide this block when disconnected | true

Placeholder | Value | Type | Unit
icon | Icon based on connection’s status | Icon | -
bat_icon | Battery level indicator (only when connected and if supported) | Icon | -
bat_charge | Battery charge level (only when connected and if supported) | Number | %
notif_icon | Only when connected and there are notifications | Icon | -
notif_count | Number of notifications on your phone (only when connected and non-zero) | Number | -
name | Name of your device as reported by KDEConnect (if available) | Text | -
connected | Present if your device is connected | Flag | -

  Example

Do not show the name, do not set the “good” state.

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

  Icons Used

•   bat (as a progression)

•   bat_charging (as a progression)

•   notification

•   phone

•   phone_disconnected

  keyboard_layout

Keyboard layout indicator

Four drivers are available: - setxkbmap which polls setxkbmap to get the current layout - localebus which can read asynchronous updates from the systemd org.freedesktop.locale1 D-Bus path - kbddbus which uses kbdd (https://github.com/qnikst/kbdd) to monitor per-window layout changes via DBus - sway which can read asynchronous updates from the sway IPC

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

  Configuration

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

Key | Value | Type
layout | Keyboard layout name | String
variant | Keyboard variant. Only localebus, sway and kbddbus are supported so far. | String

  Examples

Check setxkbmap every 15 seconds:

    [[block]]
    block = "keyboard_layout"
    driver = "setxkbmap"
    interval = 15

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"

  load

System load average

  Configuration

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

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
1m | 1 minute load average | Number | -
5m | 5 minute load average | Number | -
15m | 15 minute load average | Number | -

  Example

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

  Icons Used

•   cogs

  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

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders. | " $icon $status "
inboxes | List of maildir inboxes to look for mails in. Supports path expansions e.g. ~. | Required
threshold_warning | Number of unread mails where state is set to warning. | 1
threshold_critical | Number of unread mails where state is set to critical. | 10
interval | Update interval, in seconds. | 5
display_type | Which part of the maildir to count: "new", "cur", or "all". | "new"

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
status | Number of emails | Number | -

  Examples

    [[block]]
    block = "maildir"
    interval = 60
    inboxes = ["/home/user/mail/local", "/home/user/mail/gmail/Inbox"]
    threshold_warning = 1
    threshold_critical = 10
    display_type = "new"

  Icons Used

•   mail

  memory

Memory and swap usage

  Configuration

Key | Values | Default
format | A string to customise the output of this block when in “Memory” view. See below for available placeholders. | " $icon $mem_avail.eng(prefix:M)/$mem_total.eng(prefix:M)($mem_total_used_percents.eng(w:2)) "
format_alt | If set, block will switch between format and format_alt on every click | None
interval | Update interval in seconds | 5
warning_mem | Percentage of memory usage, where state is set to warning | 80.0
warning_swap | Percentage of swap usage, where state is set to warning | 80.0
critical_mem | Percentage of memory usage, where state is set to critical | 95.0
critical_swap | Percentage of swap usage, where state is set to critical | 95.0

Placeholder | Value | Type | Unit
icon | Memory icon | Icon | -
icon_swap | Swap icon | Icon | -
mem_total | Total physical ram available | Number | Bytes
mem_free | Free memory not yet used by the kernel or userspace (in general you should use mem_avail) | Number | Bytes
mem_free_percents | as above but as a percentage of total memory | Number | Percents
mem_avail | Kernel estimate of usable free memory which includes cached memory and buffers | Number | Bytes
mem_avail_percents | as above but as a percentage of total memory | Number | Percents
mem_total_used | mem_total - mem_free | Number | Bytes
mem_total_used_percents | as above but as a percentage of total memory | Number | Percents
mem_used | Memory used, excluding cached memory and buffers; same as htop’s green bar | Number | Bytes
mem_used_percents | as above but as a percentage of total memory | Number | Percents
buffers | Buffers, similar to htop’s blue bar | Number | Bytes
buffers_percent | as above but as a percentage of total memory | Number | Percents
cached | Cached memory (taking into account ZFS ARC cache), similar to htop’s yellow bar | Number | Bytes
cached_percent | as above but as a percentage of total memory | Number | Percents
swap_total | Swap total | Number | Bytes
swap_free | Swap free | Number | Bytes
swap_free_percents | as above but as a percentage of total memory | Number | Percents
swap_used | Swap used | Number | Bytes
swap_used_percents | as above but as a percentage of total memory | Number | Percents

Action | Description | Default button
toggle_format | Toggles between format and format_alt | Left

  Example

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

  Icons Used

•   memory_mem

•   memory_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

Key | Values | Default
text | Text that will be displayed when the block is inactive. | Required
items | A list of “items”. See examples below. | 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 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). This includes:

•   Spotify

•   VLC

•   mpd (via mpDris2 (https://github.com/eonpatapon/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

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders. | ” $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 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.”. | None
interface_name_exclude | A list of regex patterns for player MPRIS interface names to ignore. | ["playerctld"]
separator | String to insert between artist and title. | " - "
seek_step_secs | Positive number of seconds to seek forward/backward when scrolling on the bar. Does not need to be an integer. | 1
volume_step | The percent volume level is increased/decreased for the selected audio device when scrolling. Capped automatically at 50. | 5

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

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

Action | Default button
play_pause | Left on $play
next | Left on $next
prev | Left on $prev
next_player | Right
seek_forward | Wheel Up
seek_backward | Wheel Down
volume_up | -
volume_down | -

  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:

    [[block]]
    block = "music"
    [[block.click]]
    button = "left"
    action = "play_pause"

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

•   music_next

•   music_play

•   music_prev

•   volume_muted

•   volume (as a progression)

  net

Network information

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

  Configuration

Key | Values | Default
device | Network interface to monitor (as specified in /sys/class/net/). Supports regex. | 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. | " $icon ^icon_net_down $speed_down.eng(prefix:K) ^icon_net_up $speed_up.eng(prefix:K) "
format_alt | If set, block will switch between format and format_alt on every click | None
interval | Update interval in seconds | 2
missing_format | Same as format if the interface cannot be connected (or missing). | " × "

Action | Description | Default button
toggle_format | Toggles between format and format_alt | Left

Placeholder | Value | Type | Unit
icon | Icon based on device’s type | Icon | -
speed_down | Download speed | Number | Bytes per second
speed_up | Upload speed | Number | Bytes per second
graph_down | Download speed graph | Text | -
graph_up | Upload speed graph | Text | -
device | The name of device | Text | -
ssid | Netfork SSID (WiFi only) | Text | -
frequency | WiFi frequency | Number | Hz
signal_strength | WiFi signal | Number | %
bitrate | WiFi connection bitrate | Number | Bits per second
ip | IPv4 address of the iface | Text | -
ipv6 | IPv6 address of the iface | Text | -

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

  Icons Used

•   net_loopback

•   net_vpn

•   net_wired

•   net_wireless

•   net_up

•   net_down

  notify

Display and toggle the state of notifications daemon

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

  Configuration

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

Placeholder | Value | Type | Unit
icon | Icon based on notification’s state | Icon | -
notification_count[1] | The number of notification (omitted if 0) | Number | -
paused | Present only if notifications are disabled | Flag | -

Action | Default button
toggle_paused | Left
show | -

  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

•   bell-slash

  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

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

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
count | Number of messages for the query | Number | -

  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

  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.

  Configuration

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

Placeholder | Type | Unit
icon | Icon | -
name | Text | -
utilization | Number | Percents
memory | Number | Bytes
temperature | Number | Degrees
fan_speed | Number | Percents
clocks | Number | Hertz
power | Number | Watts

Action | Default button
toggle_mem_total | Left on $memory
toggle_fan_controlled | Left on $fan_speed
fan_speed_up | Wheel Up on $fan_speed
fan_speed_down | Wheel Down on $fan_speed

  Example

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

  Icons Used

•   gpu

  TODO

•   Provide a mappings option similar to keyboard_layout’s to map GPU names to labels?

  pacman

Pending updates available on pacman or an AUR helper.

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/. 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). 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 other number if 1 is being used by some other block):

    [[block]]
    block = "pacman"
    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

  Configuration

Key | Values | Default
interval | Update interval, in seconds. If setting aur_command then set interval appropriately as to not exceed the AUR’s daily rate limit. | 600
format | A string to customise the output of this block. See below for available placeholders. | " $icon $pacman.eng(w:1) "
format_singular | Same as format but for when exactly one update is available. | " $icon $pacman.eng(w:1) "
format_up_to_date | Same as format but for when no updates are available. | " $icon $pacman.eng(w:1) "
warning_updates_regex | Display block as warning if updates matching regex are available. | None
critical_updates_regex | Display block as critical if updates matching regex are available. | None
aur_command | AUR command to check available updates, which outputs in the same format as pacman. e.g. yay -Qua | Required if $both or $aur are used

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
pacman | Number of updates available according to pacman | Number | -
aur | Number of updates available according to <aur_command> | Number | -
both | Cumulative number of updates available according to pacman and <aur_command> | Number | -

  Examples

pacman only config:

    [[block]]
    block = "pacman"
    interval = 600
    format = " $icon $pacman updates available "
    format_singular = " $icon $pacman update available "
    format_up_to_date = " $icon system up to date "
    critical_updates_regex = "(linux|linux-lts|linux-zen)"
    [[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/ | wofi --show dmenu"
    [[block.click]]
    ### Updates the block on right click
    button = "right"
    update = true

pacman only config using warnings with ZFS modules:

    [[block]]
    block = "pacman"
    interval = 600
    format = " $icon $pacman updates available "
    format_singular = " $icon $pacman 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)"

pacman and AUR helper config:

    [[block]]
    block = "pacman"
    interval = 600
    error_interval = 300
    format = " $icon $pacman + $aur = $both updates available "
    format_singular = " $icon $both update available "
    format_up_to_date = " $icon system up to date "
    critical_updates_regex = "(linux|linux-lts|linux-zen)"
    ### aur_command should output available updates to stdout (ie behave as echo -ne "update\n")
    aur_command = "yay -Qua"

  Icons Used

•   update

  pomodoro

A pomodoro timer (https://en.wikipedia.org/wiki/Pomodoro_Technique)

  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

Key | Values | Default
format | A string to customise the output of this block. | ” $icon{ $message|} “
message | Message when timer expires | "Pomodoro over! Take a break!"
break_message | Message when break is over | "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. | 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. | false

Placeholder | Value | Type
icon | A static icon | Icon
message | Current message | Text

  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

•   pomodoro_started

•   pomodoro_stopped

•   pomodoro_paused

•   pomodoro_break

  TODO

•   Use different icons.

•   Use format strings.

  rofication

The number of pending notifications in rofication-daemon

A different color is used if there are critical notifications.

  Configuration

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

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
num | Number of pending notifications | Number | -

  Example

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

  Icons Used

•   bell

  service_status

Display the status of a service

Right now only systemd is supported.

  Configuration

Key | Values | Default
driver | Which init system is running the service. Available drivers are: "systemd" | "systemd"
service | The name of the service | Required
active_format | A string to customise the output of this block. See below for available placeholders. | " $service active "
inactive_format | A string to customise the output of this block. See below for available placeholders. | " $service inactive "
active_state | A valid [State] | [State::Idle]
inactive_state | A valid [State] | [State::Critical]

Placeholder | Value | Type | Unit
service | The name of the service | Text | -

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

  Examples

Change the default scrolling step width to 3 percent:

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

    [[block]]
    block = "sound"
    format = " $icon $output_description{ $volume|} "

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

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"

  Configuration

Key | Values | Default
driver | "auto", "pulseaudio", "alsa". | "auto" (Pulseaudio with ALSA fallback)
format | A string to customise the output of this block. See below for available placeholders. | $icon {$volume.eng(w:2) |}
name | PulseAudio device name, or the ALSA control name as found in the output of amixer -D yourdevice scontrols. | 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
device_kind | PulseAudio device kind: source or sink. | "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. | false
step_width | The percent volume level is increased/decreased for the selected audio device when scrolling. Capped automatically at 50. | 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. | None
show_volume_when_muted | Show the volume even if it is currently muted. | false
headphones_indicator | Change icon when headphones are plugged in (pulseaudio only) | false
mappings | Map output_name to custom name. | None

Placeholder | Value | Type | Unit
icon | Icon based on volume | Icon | -
volume | Current volume. Missing if muted. | Number | %
output_name | PulseAudio or ALSA device name | Text | -
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) | Text | -

Action | Default button
toggle_mute | Right
volume_up | Wheel Up
volume_down | Wheel Down

  Icons Used

•   microphone_muted (as a progression)

•   microphone (as a progression)

•   volume_muted (as a progression)

•   volume (as a progression)

•   headphones

  speedtest

Ping, download, and upload speeds

This block which requires speedtest-cli (https://github.com/sivel/speedtest-cli).

  Configuration

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders. | " ^icon_ping $ping ^icon_net_down $speed_down ^icon_net_up $speed_up "
interval | Update interval in seconds | 1800

Placeholder | Value | Type | Unit
ping | Ping delay | Number | Seconds
speed_down | Download speed | Number | Bits per second
speed_up | Upload speed | Number | Bits per second

  Example

Show only ping (with an icon)

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

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

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

  Icons Used

•   ping

•   net_down

•   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

Key | Values | Default
interval | Update interval in seconds | 600 (10min)
warning_threshold | The threshold of pending (or started) tasks when the block turns into a warning state | 10
critical_threshold | The threshold of pending (or started) tasks when the block turns into a critical state | 20
filters | A list of tables with the keys name and filter. filter specifies the criteria that must be met for a task to be counted towards this filter. | [{name = "pending", filter = "-COMPLETED -DELETED"}]
format | A string to customise the output of this block. See below for available placeholders. | " $icon $count.eng(w:1) "
format_singular | Same as format but for when exactly one task is pending. | " $icon $count.eng(w:1) "
format_everything_done | Same as format but for when all tasks are completed. | " $icon $count.eng(w:1) "
data_location | Directory in which taskwarrior stores its data files. Supports path expansions e.g. ~. | "~/.task"

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
count | The number of tasks matching current filter | Number | -
filter_name | The name of current filter | Text | -

Action | Default button
next_filter | Right

  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"

  Icons Used

•   tasks

  tea_timer

Timer

  Configuration

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders. | ” $icon {$minutes:$seconds |}“
increment | The numbers of seconds to add each time the block is clicked. | 30
done_cmd | A command to run in sh when timer finishes. | None

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
hours | The hours remaining on the timer | Text | h
minutes | The minutes remaining on the timer | Text | mn
seconds | The seconds remaining on the timer | Text | s

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

Action | Default button
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

  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

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders | " $icon $average avg, $max max "
format_alt | If set, block will switch between format and format_alt on every click | None
interval | Update interval in seconds | 5
scale | Either "celsius" or "fahrenheit" | "celsius"
good | Maximum temperature to set state to good | 20 °C (68 °F)
idle | Maximum temperature to set state to idle | 45 °C (113 °F)
info | Maximum temperature to set state to info | 60 °C (140 °F)
warning | Maximum temperature to set state to warning. Beyond this temperature, state is set to critical | 80 °C (176 °F)
chip | Narrows the results to a given chip name. * may be used as a wildcard. | None
inputs | Narrows the results to individual inputs reported by each chip. | None

Action | Description | Default button
toggle_format | Toggles between format and format_alt | Left

Placeholder | Value | Type | Unit
min | Minimum temperature among all inputs | Number | Degrees
average | Average temperature among all inputs | Number | Degrees
max | Maximum temperature among all inputs | Number | Degrees

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

  time

The current time.

  Configuration

Key | Values | Default
format | Format string. See chrono docs (https://docs.rs/chrono/0.3.0/chrono/format/strftime/index.html#specifiers) for all options. | " $icon $timestamp.datetime() "
interval | Update interval in seconds | 10
timezone | A timezone specifier (e.g. “Europe/Lisbon”) | Local timezone

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
timestamp | The current time | Datetime | -

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

  Icons Used

•   time

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

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders | " $icon "
command_on | Shell command to enable the toggle | Yes
command_off | Shell command to disable the toggle | Yes
command_state | Shell command to determine the state. Empty output => No, otherwise => Yes. | Required
icon_on | Icon override for the toggle button while on | "toggle_on"
icon_off | Icon override for the toggle button while off | "toggle_off"
interval | Update interval in seconds. If not set, command_state will run only on click. | None

Placeholder | Value | Type | Unit
icon | Icon based on toggle’s state | Icon | -

Action | Default button
toggle | Left

  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

  Icons Used

•   toggle_off

•   toggle_on

  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

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders | " $icon $text "
interval | Update interval in seconds | 60

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
text | Current uptime | Text | -

  Example

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

  Used Icons

•   uptime

  TODO:

•   Add time or dur formatter to src/formatting/formatter.rs

  watson

Watson statistics

Watson (http://tailordev.github.io/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.

  Configuration

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders | " $text |"
show_time | Whether to show recorded time. | false
state_path | Path to the Watson state file. Supports path expansions e.g. ~. | $XDG_CONFIG_HOME/watson/state
interval | Update interval, in seconds. | 60

Placeholder | Value | Type | Unit
text | Current activity | Text | -

Action | Description | Default button
toggle_show_time | Toggle the value of show_time | 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 and met.no 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

Key | Values | Default
service | The configuration of a weather service (see below). | Required
format | A string to customise the output of this block. See below for available placeholders. Text may need to be escaped, refer to Escaping Text. | " $icon $weather $temp "
interval | Update interval, in seconds. | 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 city_id or place. | false
autolocate_interval | Update interval for autolocate in seconds or “once” | interval

  OpenWeatherMap Options

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

Key | Values | Required | Default
name | openweathermap. | Yes | None
api_key | Your OpenWeatherMap API key. | Yes | None
city_id | OpenWeatherMap’s ID for the city. | Yes* | None
place | OpenWeatherMap `By city name' search query. See here (https://openweathermap.org/current) | Yes* | None
coordinates | GPS latitude longitude coordinates as a tuple, example: ["39.2362","9.3317"] | Yes* | None
units | Either "metric" or "imperial". | No | "metric"
lang | Language code. See here (https://openweathermap.org/current#multi). Currently only affects weather_verbose key. | No | "en"

One of city_id, place or coordinates is required. If more than one are supplied, city_id takes precedence over place which takes place over coordinates.

The options api_key, city_id, place can be omitted from configuration, in which case they must be provided in the environment variables OPENWEATHERMAP_API_KEY, OPENWEATHERMAP_CITY_ID, OPENWEATHERMAP_PLACE.

  met.no Options

Key | Values | Required | Default
name | metno. | Yes | None
coordinates | GPS latitude longitude coordinates as a tuple, example: ["39.2362","9.3317"] | Required if autolocate = false | None
lang | Language code: en, nn or nb | No | en
altitude | Meters above sea level of the ground | No | Approximated by server

Met.no does not support location name.

  Available Format Keys

Key | Value | Type | Unit
icon | Icon representing the weather | Icon | -
location | Location name (exact format depends on the service) | Text | -
temp | Temperature | Number | degrees
apparent | Australian Apparent Temperature | Number | degrees
humidity | Humidity | Number | %
weather | Textual brief description of the weather, e.g. “Raining” | Text | -
weather_verbose | Textual verbose description of the weather, e.g. “overcast clouds” | Text | -
wind | Wind speed | Number | -
wind_kmh | Wind speed. The wind speed in km/h | Number | -
direction | Wind direction, e.g. “NE” | Text | -

  Example

Show detailed weather in San Francisco through the OpenWeatherMap service:

    [[block]]
    block = "weather"
    format = " $icon $weather ($location) $temp, $wind m/s $direction "
    [block.service]
    name = "openweathermap"
    api_key = "XXX"
    city_id = "5398563"
    units = "metric"

  Used Icons

•   weather_sun (when weather is reported as “Clear”)

•   weather_rain (when weather is reported as “Rain” or “Drizzle”)

•   weather_clouds (when weather is reported as “Clouds”, “Fog” or “Mist”)

•   weather_thunder (when weather is reported as “Thunderstorm”)

•   weather_snow (when weather is reported as “Snow”)

•   weather_default (in all other cases)

  xrandr

X11 screen information

X11 screen information (name, brightness, resolution). With a click you can toggle through your active screens and with wheel up and 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) and here (https://github.com/greshake/i3status-rust/issues/668) when using this block. The cause is currently unknown, however setting a higher update interval may help.

  Configuration

Key | Values | Default
format | A string to customise the output of this block. See below for available placeholders. | " $icon $display $brightness_icon $brightness "
step_width | The steps brightness is in/decreased for the selected screen (When greater than 50 it gets limited to 50). | 5
interval | Update interval in seconds. | 5

Placeholder | Value | Type | Unit
icon | A static icon | Icon | -
display | The name of a monitor | Text | -
brightness | The brightness of a monitor | Number | %
brightness_icon | A static icon | Icon | -
resolution | The resolution of a monitor | Text | -
res_icon | A static icon | Icon | -

Action | Default button
cycle_outputs | Left
brightness_up | Wheel Up
brightness_down | Wheel Down

  Example

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

  Used Icons

•   xrandr

•   backlight_full

•   resolution

NOTES

  [1]

when using notification_count with the dunst driver use dunst > 1.9.0

THEMES

  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 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 icons subdirectory instead of themes. - You can omit the .toml extension while specifying file parameter. - 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 (https://github.com/greshake/i3status-rust/blob/master/gen-screenshots/screenshot_config.toml) with this swaybar config (https://github.com/greshake/i3status-rust/blob/master/gen-screenshots/swayconfig_i3rs).

•   plain (default) [IMAGE: plain (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/plain.png)]

•   solarized-dark [IMAGE: solarized-dark (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/solarized-dark.png)]

•   solarized-light [IMAGE: solarized-light (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/solarized-light.png)]

•   slick [IMAGE: slick (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/slick.png)]

•   modern [IMAGE: modern (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/modern.png)]

•   bad-wolf [IMAGE: bad-wolf (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/bad-wolf.png)]

•   gruvbox-light [IMAGE: gruvbox-light (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/gruvbox-light.png)]

•   gruvbox-dark [IMAGE: gruvbox-dark (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/gruvbox-dark.png)]

•   space-villain [IMAGE: space-villain (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/space-villain.png)]

•   native (like plain with no background and native separators) [IMAGE: native (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/native.png)]

•   semi-native (like native but with background) [IMAGE: semi-native (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/semi-native.png)]

•   nord-dark (polar night) [IMAGE: nord-dark (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/nord-dark.png)]

•   dracula [IMAGE: dracula (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/dracula.png)]

•   srcery [IMAGE: srcery (https://raw.githubusercontent.com/greshake/i3status-rust/master/img/themes/srcery.png)]

  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)

•   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). 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 = " | | "
    bat_full = " |X| "
    bat_charging = " |^| "
    bat_discharging = " |v| "

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"

  Available theme overrides

All bg and fg overrides are 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.

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

  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 (https://github.com/greshake/i3status-rust/tree/master/files/icons) for a complete list of icons.

CONFORMING TO
The JSON output produced by this program and understood by compatible bars is described at <https://i3wm.org/docs/i3bar-protocol.html> and in swaybar-protocol(7).

SEE ALSO
i3status(1), i3bar(1), sway-bar(5), swaybar-protocol(7)