river

river is a wlroots-based Wayland dynamic tiling compositor, inspired by, but not based on xmonad and bspwm. Configuration is by an external executable file.

Its declared design goals are:

Simple and predictable behavior, river should be easy to use and have a low cognitive load.
Window management based on a stack of views and tags.
Dynamic layouts generated by external, user-written executables. A default rivertile layout generator is provided.
Scriptable configuration and control through a custom Wayland protocol and separate riverctl binary implementing it.

Installation

River is installed with the river package or AUR git package river-git^AUR.

Starting

A single executable file is used as a configuration file. No initialisation file is set up for the user by default, so no keybindings or default applications are available until an init file is created. Note that this includes the exit keybinding, so set up in tty or another desktop environment before running river.

An example config init file is available in /usr/share/river/example/. Copy this as ~/.config/river/init and ensure it is executable.

Manually

Enter river (exits to tty with user still logged in) or exec river (more securely exits to tty with user logged out)

From TTY

River can be autostarted in a similar manner to startx, by setting up the environment variable checks in .bash_profile or the equivalent file for other shells. See Xinit#Autostart X at login, replacing $DISPLAY with $WAYLAND_DISPLAY, and running exec river.

Display manager

River does not officially support display managers but many will work with no or minimal effort. A session entry is installed by default in /usr/share/wayland-sessions/.

Configuration

The configuration file can be a shell script or executable program, comprising a list of riverctl individual commands which define key bindings, input settings and window rules. It is executed once at start-up but can be re-run like any other shell script (consider the effects of duplicating any autostarted spawned actions). Each setting can also be run individually by simply running the relevant riverctl line in a terminal. This allows temporary override of the init settings, dynamic updates and testing new settings.

For example, to map the shortcut Super+PrtSc to take a screenshot with the application grim and display a temporary notification:

riverctl map normal Super Print spawn "grim && notify-send -t 2000 'Screenshot taken'"

The spawn command can launch any application or script but expects a single word argument. Quote any longer expressions.

Keyboard layout

riverctl keyboard-layout gb

Multiple layouts can be entered as a comma-separated list, e.g. gb,fr.

Variables and other shell constructs can be used: mod='Mod4', set term foot, etc, as per your shell.

Touchpad examples

Certain touchpad behaviour and focus preferences are available.

riverctl input pointer-2-7-SynPS/2_Synaptics_TouchPad tap enabled
riverctl focus-follows-cursor normal

Exact keyboard, mouse and touchpad models for use in these settings can be identified using:

riverctl list-inputs

Window rules

It is sometimes desirable to set certain windows to be non-tiling by default. Floating windows can be defined by class or title:

riverctl float-filter-add app-id 'galculator'
riverctl float-filter-add title 'File Operation Progress'

Note that new rule-add settings will be introduced for River 0.3 and this syntax will change to fit these broader definitions:

riverctl rule-add -app-id 'galculator' float

Usage

Autostart

Use riverctl spawn without a keybinding to launch any executable at startup, for example:

riverctl spawn "i3-battery-popup -n -m 'Battery Low!'"

Tips and tricks

Scratchpads

River does not define any scratchpads by default, but these can be set up on any tag beyond the default 0-9. First, define the tag number, then the key mapping to move an application to the scratchpad tag and toggle its appearance, and, finally, prevent new windows being assigned to the scratchpad.

scratch_tag=$((1 << 20 ))

riverctl map normal Super P toggle-focused-tags ${scratch_tag}		# toggle the scratchpad
riverctl map normal Super+Shift P set-view-tags ${scratch_tag}		# send windows to the scratchpad

# Set spawn tagmask to ensure new windows do not have the scratchpad tag unless explicitly set.
all_but_scratch_tag=$(( ((1 << 32) - 1) ^ $scratch_tag ))
riverctl spawn-tagmask ${all_but_scratch_tag}

Modes

River supports modes for key mapping, which allows for reuse of mappings, and combinations of fewer keys. There are two default modes of 'normal' and 'locked' (defining allowed key mappings when the screen is locked). Custom modes can be added. Eg. if floating windows are rarely used, the key mapping to manipulate those windows can be defined in a 'float' mode. Entry and exit key mappings for the mode are set as the first and last mappings, with other mapping between these.

riverctl declare-mode float
riverctl map normal Super R enter-mode float		# Super+R to enter float mode
 
### Floating window mappings but note that these also apply to tiled windows.
#
# Super {Arrows} to move views
  riverctl map float Super Left move left 100
  riverctl map float Super Down move down 100
  riverctl map float Super Up move up 100
  riverctl map float Super Right move right 100
 
# Alt+{arrows} to snap views to screen edges
  riverctl map float Alt Left snap left
  riverctl map float Alt Down snap down
  riverctl map float Alt Up snap up
  riverctl map float Alt Right snap right
 
# Shift+{arrows} to resize views
  riverctl map float Shift Left resize horizontal -100
  riverctl map float Shift Down resize vertical 100
  riverctl map float Shift Up resize vertical -100
  riverctl map float Shift Right resize horizontal 100
 
riverctl map float None Escape enter-mode normal	# Escape to exit float mode and return to normal mode

External tools

In common with many other Wayland minimalist tiling clients, other tools are not included. Example external bars, screenshot tools, launchers, etc. are listed in the River wiki, including several with River-specific functionality.

Troubleshooting

Note that floating window modifiers also work on tiled windows, making them floating and giving potentially unpredictable layouts.

The current stable version of River does not support autostarting windows on specific workspaces, but the git version (0.3) introduces a rule-add option for riverctl, bringing this functionality.