Skip to main content
otter-bar is the Otter Shell status bar. It anchors to the top or bottom of each output through zwlr_layer_shell_v1. Config and theme reload without a restart.

​
Features

  • Workspace indicator and switcher (otter-tag, Mango/dwl IPC, ext-workspace)
  • Active window title with icon
  • Clock with timezone-aware formatting and date tooltip
  • Battery via UPower (auto-hides when no battery)
  • Brightness from /sys/class/backlight/
  • Power profiles (power-profiles-daemon / tuned-ppd)
  • CPU, temperature, memory, and network widgets
  • Volume via PipeWire with scroll-to-adjust and device popup
  • MPRIS media player: left-click opens playback controls; middle-click toggles play/pause. Intentionally blurred artwork covers the full popup with aspect-preserving cropping.
  • System tray (StatusNotifierItem) with context menus
  • Do Not Disturb toggle shared with notifications and OSD
  • Night Light toggle (nightlight) for otter-nightlight
  • Keyboard layout indicator (keyboard_layout)
  • Weather from the otter-weather cache
  • Custom button widgets with an icon and a command
  • HiDPI scaling per output

​
Usage

Add it to compositor autostart: see Session setup. The menu button runs otter-launcher by default. Change it with button_menu_command. The power button runs otter-logout by default. It is enabled and sits at the end of the default right layout.

​
Lua widgets

The built-in widgets are drawn by Lua plugins by default. otter-bar installs them under /usr/share/otter-shell/plugins/<name>. A layout name such as clock loads plugin:clock, which reads the same clock_* keys from otter-bar.conf and draws the same widget. Every button_<name> loads the shared button plugin. To keep the native widget instead, do one of these:
  • Write native:<name> in the layout, for example native:clock.
  • Set <plugin-id>_enabled = false in ~/.config/otter-shell/plugins.conf, for example clock_enabled = false. For the shared button renderer, use button_enabled = false.
The bar also falls back to the native widget when a plugin is missing or fails to load. To override a bundled widget, copy its directory to ~/.local/share/otter-shell/plugins/<name> and edit it. Third-party widgets load as plugin:<id> slots. Enable them in otter-settings Plugins, then drag the chip into the layout. See Plugins. To write your own widget, see Plugin development. otter-bluetooth-plugin installs plugin:bluetooth-applet and depends on bluez and otter-term. Enable it under Plugins, then add plugin:bluetooth-applet to a layout. Click the chip for status and device controls. Advanced device management opens bluetoothctl in Otter Terminal.

​
Configuration

Config: ~/.config/otter-shell/otter-bar.conf (fallback: /etc/otter-shell/otter-bar.conf). Created on first run.
Drag widgets in otter-settings instead of editing layout strings.
Key settings:
Widget color fields are optional. Omit them to inherit from theme.conf. Saving theme.conf updates bar widget colors without editing otter-bar.conf.

​
Do Not Disturb

Add dnd to any layout section. Click its bell icon to pause or resume notification and OSD popups. Notifications stay queued while DND is on.

​
Night Light

Add nightlight to any layout section. Left-click enables or disables otter-nightlight. Right-click for temperature presets, the schedule window, and a one-hour suspend. The widget does nothing if the daemon is not running.

​
Keyboard layout

Add keyboard_layout to a layout section to show the current XKB layout. Set keyboard_layout_notify_on_change = true to show layout changes through otter-osd. Niri and Hyprland report layouts over native IPC. Other compositors rely on Wayland keyboard events.

​
System tray

Set system_tray_always_show = true to show tray icons without the expand button.

​
Weather widget

Add weather to a layout section, then run the cache watcher:
Set coordinates in ~/.config/otter-shell/otter-weather.conf. See otter-weather.

​
Calendar popover

Left-click the clock to open the calendar popover. Click the bar or outside the popover to close it. The popover lists today’s agenda lines from ~/.config/otter-shell/agenda, one YYYY-MM-DD text entry per line. Set clock_agenda_path to read another file.

​
Dependencies

  • Wayland compositor with zwlr_layer_shell_v1
  • D-Bus services for battery, power profiles, MPRIS, network, and system tray
  • PipeWire for the volume widget