Configuration

tablero reads an optional TOML file from $XDG_CONFIG_HOME/tablero/config.toml, falling back to $HOME/.config/tablero/config.toml. When it is absent the bar runs on the defaults below. The document may be partial: any omitted field falls back to its default.

Caution

Invalid configuration is a hard error, never a silent fallback. An unknown key, unknown widget name, or malformed color stops startup with a message naming the file. During hot reload, invalid saves keep the last valid bar.

A ready-to-copy ARC Raiders-inspired preset shows the full styling surface:

mkdir -p ~/.config/tablero
curl --fail --location \
  https://raw.githubusercontent.com/piny4man/tablero/main/crates/tablero/config.example.toml \
  --output ~/.config/tablero/config.toml

Reference

Every value below is the built-in default.

height = 32

[bar]
margin = 0
gap = 0
modules-left = ["workspaces"]
modules-center = ["title"]
modules-right = ["clock", "battery", "system", "network", "power-profiles-daemon"]

[theme]
background = "#181818" # fill behind every widget
foreground = "#eaeaea" # default text color
accent     = "#eaeaea" # emphasis color (e.g. the active workspace)

[font]
# family = "JetBrains Mono"   # unset = system default font
size = 16.0

Key	Type	Default	Notes
appearance.theme_file	string (opt.)	unset	Path to a Swatches v1 theme. Relative to this config file; ~/ expands.
height	integer (px)	32	Bar height; also drives the exclusive zone.
bar.background	hex color (opt.)	unset	Bar fill; inherits theme.background when unset.
bar.margin	integer (px)	0	Inset around the full module row.
bar.gap	integer (px)	0	Gap between adjacent modules in a zone.
bar.modules-left	list of strings	["workspaces"]	Modules packed against the left edge.
bar.modules-center	list of strings	["title"]	Modules centered independently of the edge zones.
bar.modules-right	list of strings	see above	Modules packed against the right edge.
theme.background	hex color	"#181818"	Fill behind every widget.
theme.foreground	hex color	"#eaeaea"	Default text color.
theme.accent	hex color	"#eaeaea"	Emphasis color.
font.family	string (opt.)	system font	Font family name.
font.size	float (px)	16.0	Text size.

Repeated module names are de-duplicated, keeping the first position. Sizes are logical pixels and scale with the output.

Shared Swatches theme

Set [appearance] theme_file to a Swatches v1 TOML file to fill absent theme colors and font family:

[appearance]
theme_file = "~/themes/swatches.toml"

Swatches v1 value	tablero fallback
colors.background	theme.background
colors.foreground	theme.foreground
colors.accent	theme.accent
font.family	font.family

Precedence is defaults → shared theme → explicit app theme/font → bar/widget/state/monitor specificity. An explicit value equal to the default still counts as explicit. A missing or invalid theme is a startup error; during reload it is logged and the current bar stays up.

Per-widget styling

Every [widget.<name>] table accepts fills and outlines without changing the global theme:

[widget.clock]
background = "#292b1d"
foreground = "#f0d77b"
border = "#766b36"
border-width = 1
radius = 2
padding = 10

background, foreground, accent and border accept six- or eight-digit hex colors. When border is set and border-width is omitted, the width defaults to one logical pixel.

The battery supports format placeholders ({icon}, {percent}, {state}, {time}) and a charging state:

[widget.battery]
format = "{icon} {percent}%"

[widget.battery.charging]
background = "#2df18520"
foreground = "#5ff5a0"
border = "#2df185"

Icons

Widget icons are built-in vector art drawn with tiny-skia; no icon font is shipped. Each icon-bearing widget takes an icon field:

• omitted → the built-in icon
• icon = "none" → label only
• icon = "<text>" → any literal string, such as a Nerd Font glyph or emoji

icon-size = <px> (1–64 logical pixels) enlarges a widget’s icon without changing its label: it sets the built-in icon’s edge, or the font size of a text glyph from icon or format-icons. Unset, icons follow the bar font size.

Hover highlight

Hovering a clickable widget, or one with a tooltip, lifts its pill: by default a tenth of the foreground is mixed into the background. A [widget.<name>.hover] table sets the hover background, foreground or border; unset channels keep the widget’s own colors, so a widget that recolors by state keeps that color while hovered.

[widget.volume.hover]
background = "#2a1428"
border = "#7decff"

Click handlers

on-click = "/path/to/executable" on a [widget.<name>] table spawns that program on left-click, with no shell.

[widget.power]
on-click = "/usr/bin/wlogout"
on-click-right = "/usr/bin/hyprlock"

[widget.volume]
on-click = "/usr/bin/pavucontrol"

[widget.clock]
on-click = "/usr/bin/gnome-calendar"

• Prefer absolute paths. A leading ~ is expanded at click time; absolute paths must exist and be executable.
• Bare names resolve through the bar process’s PATH.
• No pipes, &&, env vars or globs. Pass arguments by whitespace or as a TOML list: on-click = ["gtk-launch", "org.gnome.Calendar"]. Multi-step logic belongs in a small script.
• bluetooth, volume, updates, network, clock and power honor on-click. Power, network and clock also accept on-click-right.
• If nothing happens on click, run with RUST_LOG=tablero::command=info to see spawn failures.