WIDERIVER(1)
💅 wideriver(1) — your fave tiling window manager 💅
okay so we're doing the WIDERIVER(1) manual page, and this first part is literally the setup + layout lore. bestie, it's giving "tiny window manager, huge main character energy." ✨
🌸 NAME 🌸
wideriver — a tiling window manager for the river-classic wayland compositor. no cap, that's the whole vibe. 💖
✨ SYNOPSIS ✨
wideriver [OPTION...|COMMAND...]💖 DESCRIPTION 💖
Tiling window manager for the river-classic wayland compositor, inspired by dwm and xmonad. it's iconic, it's cozy, it's a whole layout situation. 🫶
here's the feature vibe check:
- Per-tag state — yes, tags keep their own state, periodt. 🎀
- Master/stack(s) left, right and wide layouts — the classic trio, but make it flexible.
- Monocle with alternate borders — one window, full focus, very main character. 👑
- Layout toggling — swap layouts without losing your mind.
- Dwindling, diminishing and even stacks — stack behavior for every mood. 🌈
- Inner, outer and smart gaps — gaps, gaps, and more gaps, bestie. 💅
here's the layout cheat sheet, with all the exact symbols and directions:
- Left — symbol
│ ├─┤; master Left; stack Right; directions Down, Right. - Right — symbol
├─┤ │; master Right; stack Left; directions Down, Left. - Top — symbol
├─┬─┤; master Top; stack Bottom; directions Right, Down. - Bottom — symbol
├─┴─┤; master Bottom; stack Top; directions Right, Up. - Wide — symbol
├─┤ ├─┤; master Mid; stack Left with directions Up, Left, and stack Right with directions Down, Right. - Monocle — symbol
│ n │; master All; stack -; directions -.
🚀 QUICK START 🚀
your quick-start config lives at $XDG_CONFIG_HOME/river/init. slay. 💖
first: set server side decorations. this is required to display borders on all windows. not optional, bestie.
riverctl rule-add ssdnext: set the layout generator and start it. all defaults are shown here, none are required. the log file is strongly recommended. 🔥
# set layout manager
riverctl default-layout wideriver
# start layout manager
wideriver \
--layout left \
--layout-alt monocle \
--stack dwindle \
--count-master 1 \
--ratio-master 0.50 \
--count-wide-left 0 \
--ratio-wide 0.35 \
--no-smart-gaps \
--inner-gaps 0 \
--outer-gaps 0 \
--border-width 2 \
--border-width-monocle 0 \
--border-width-smart-gaps 0 \
--border-color-focused "0x93a1a1" \
--border-color-focused-monocle "0x586e75" \
--border-color-unfocused "0x586e75" \
--log-threshold info \
--wide-first left \
> "/tmp/wideriver.${XDG_VTNR}.${USER}.log" 2>&1 &create some command mappings, e.g. these absolute bangers:
riverctl map normal $mod1 up send-layout-cmd wideriver "--layout monocle"
riverctl map normal $mod1 down send-layout-cmd wideriver "--layout wide"
riverctl map normal $mod1 left send-layout-cmd wideriver "--layout left"
riverctl map normal $mod1 right send-layout-cmd wideriver "--layout right"
riverctl map normal $mod1 Space send-layout-cmd wideriver "--layout-toggle"
riverctl map normal $mod1 plus send-layout-cmd wideriver "--ratio +0.025"
riverctl map normal $mod1 equal send-layout-cmd wideriver "--ratio 0.35"
riverctl map normal $mod1 minus send-layout-cmd wideriver "--ratio -0.025"
riverctl map normal $mod2 plus send-layout-cmd wideriver "--count +1"
riverctl map normal $mod2 equal send-layout-cmd wideriver "--count 1"
riverctl map normal $mod2 minus send-layout-cmd wideriver "--count -1"
riverctl map normal $mod2 e send-layout-cmd wideriver "--stack even"
riverctl map normal $mod2 w send-layout-cmd wideriver "--stack dwindle"
riverctl map normal $mod2 i send-layout-cmd wideriver "--stack diminish"🦋 EXAMPLE LAYOUTS AND STACKS 🦋
🌿 Left, Dwindle 🌿
riverctl send-layout-cmd wideriver "--layout left --stack dwindle --count 1 --ratio 0.5" Master Stack
____________________________________________________________
| | |
| | |
| | 2 |
| | |
| | |
| 1 |_____________________________|
| | | |
| | | 4 |
| | 3 |______________|
| | | | |
| | | 5 | 6 |
|____________________________|______________|______|_______|the master area occupies half of the available space and contains one view. 🎀
the stack is filled in a diminishing manner in a downward then rightward directions.
2 may be moved into the master area with riverctl send-layout-cmd wideriver "--count +1" and will be evenly placed below 1.
🌸 Right, Even 🌸
riverctl send-layout-cmd wideriver "--layout right --stack even --count 2 --ratio 0.55" Stack Master
____________________________________________________________
| | |
| | |
| 3 | 1 |
|_________________________| |
| | |
| |________________________________|
| 4 | |
|_________________________| |
| | 2 |
| | |
| 5 | |
|_________________________|________________________________|the master area occupies 55% of the available width and contains two views split evenly. 💖
the stack is split evenly and is filled in a downwards direction.
🦋 Wide, Diminish 🦋
riverctl send-layout-cmd wideriver "--layout wide --stack diminish --count 3 --ratio 0.4" Left Stack Master Right Stack
________________________________________________________________________________
| 1 | | |
|______________________| | |
| | | 5 |
| 2 | | |
| | |_______________________|
|______________________| | |
| | 4 | 6 |
| | | |
| | |_______________________|
| 3 | | 7 |
| | |_______________________|
|______________________|_______________________________|__________8____________|the master area occupies 40% of the available width and contains one view.
the left stack contains 3 views, the right stack the remainder.
the left and right stacks each occupy 30% of the available width.
5 may be moved into the master area with riverctl send-layout-cmd wideriver "--count +1". 4 will be placed at the “top” of the stack, below 3.
when started with --wide-first mid, the first window is placed in master area and subsequent windows fill the left stack:
Left Stack Master Right Stack
________________________________________________________________________________
| 6 | | |
|______________________| | |
| | | 2 |
| 7 | | |
| | |_______________________|
|______________________| | |
| | 1 | 3 |
| | | |
| | |_______________________|
| 8 | | 4 |
| | |_______________________|
|______________________|_______________________________|__________5____________|use --wide-first as a startup option; it cannot be changed at runtime. periodt.
💅 Monocle 💅
riverctl send-layout-cmd wideriver "--layout monocle" ____________________________________________________________
| |
| |
| |
| |
| |
| 1 |
| 2 |
| 3 |
| 4 |
| 5 |
| 6 |
|__________________________________________________________|only the currently focused view will be visible. iconic, honestly. 👑
🌈 LAYOUTS 🌈
Okay so the symbol is literally the layout name, and it may show up in a status bar like Waybar’s river/layout module. Dynamic settings? Those live in COMMANDS, bestie.
ratioandcountare persisted per tag and shared by all layouts exceptwide, which has its own values.stackis persisted per tag and shared by all layouts.
When multiple tags are focused, the state is persisted for only the lowest tag.
Left / Right
One master area taking up the full height of the available area, with a stack area to the left or right. Cute, classic, very demure.
ratiois the proportion of the available area occupied by master.countis the number of evenly stacked views in the master area.
Left: │ ├─┤ when count > 0 otherwise │├──┤
Right: ├─┤ │ when count > 0 otherwise ├──┤│
Wide
One master area taking up the full height of the available area, with a stack area on the left and on the right. Main character energy, honestly.
ratiois the proportion of the available area occupied by master. Stacks occupy half of the remaining area.countis the number of views in the left stack.
Master is centred when there are left and right stacks, otherwise it expands into the area that would be occupied by the empty stacks.
├─┤ ├─┤ when count > 0 otherwise ││ ├─┤
Monocle
Only one view is focused, occupying all of the available space. One icon, one throne. 👑
│ n │ with n showing number of views only when greater than 1.
🧚 STACK ARRANGEMENTS 🧚
3 arrangements are available for the stack area. It is persisted per tag and applied to all layouts for that tag. Peep the examples above for each arrangement. Stacks follow one or two directions determined by the layout.
Even
This is the “traditional” arrangement with uniformly sized stack views.
Arranged in a column or row in the first stack direction only.
Diminish
Arranged in a column or row in the first stack direction only.
Height or width diminishes according to the view’s position in the stack:
2p / (n^2 + n)
n number of views in the stack
p position in the stack
Dwindle
Arranged in a dwindling manner alternating in both stack directions.
Each view occupies half the available / remaining area.
🎀 GAPS 🎀
Gaps, in pixels, between windows may be injected. They are off by default. No gaps unless you say so, bestie.
--inner-gaps(i) are between windows.--outer-gaps(o) are between the edge of the screen and windows.--smart-gapsautomatically hides the gaps when there is only one view or monocle layout.--border-width-smart-gapsthe border width for when smart gaps hides the gaps, excluding monocle layout. For a seamless experience, set this to the same value as--border-width-monocle.
----------------------------------------------------------
| o o o o o o o o o o o o |
| ---------------------- ----------------------- |
| o | | i | | o |
| | | | | |
| o | | i | | o |
| | | ----------------------- |
| o | | i i i i i i i o |
| | | ----------------------- |
| o | | i | | o |
| | | | | |
| o | | i | | o |
| ---------------------- ----------------------- |
| o o o o o o o o o o o o |
----------------------------------------------------------✨ OPTIONS ✨
--layout monocle|left|right|top|bottom|wide— Initial layout, defaultleft.--layout-alt monocle|left|right|top|bottom|wide— Initial alternate layout, defaultmonocle. Use--layout-toggleto switch to the alternate layout.--stack even|diminish|dwindle— Initial stacking method, defaultdwindle.--count-master count— Initial number of views in the master area, default1, minimum0. Does not apply to wide layout.--ratio-master ratio— Initial proportion of the width or height the master area occupies, default0.5, minimum0.1, maximum0.9. Does not apply to wide layout.--count-wide-left count— Initial number of views in the wide layout’s left stack area, default1, minimum0. You may wish to set this to0for a more natural or intuitive feel when launching the first two views.--ratio-wide ratio— Initial proportion of the width the wide layout’s master area occupies, default0.35, minimum0.1, maximum0.9. The default value is best suited to ultrawide monitors, a value of0.5may be more useful for 16:9 monitors.--wide-first left|mid— Initial wide layout window positioning, defaultleft. Withleftthe first view is placed in the top of the left stack; withmidthe first view is placed in master. This affects both new window placement and focus jumping (zoom) behavior.--(no-)smart-gaps— Automatically hides the gaps when there is only one view or monocle layout.--inner-gaps pixels— Inner gaps width, default0, minimum0.--outer-gaps pixels— Outer gaps width, default0, minimum0.--border-width pixels— Border width for all layouts except monocle, default2, minimum0.--border-width-monocle pixels— Border width for monocle layout, default0, minimum0.--border-width-smart-gaps pixels— Border width for when smart gaps hides the gaps for all layouts except monocle, default0, minimum0. Has no effect if--no-smart-gaps.--border-color-focused 0xRRGGBB[AA]— Border color for focused views in all layouts excluding monocle, default0x93a1a1. Set it to an empty string to leave border colors unchanged:--border-color-focused ""--border-color-focused-monocle 0xRRGGBB[AA]— Border color for focused view in monocle layout, default0x586e75. It is recommended to set this to the unfocused color or a darker colour as an always focused border can be distracting. Set it to an empty string to leave border colors unchanged:--border-color-focused-monocle ""--border-color-unfocused 0xRRGGBB[AA]— Border color for unfocused views in all layouts, default0x586e75. Does not apply for monocle layout. Set it to an empty string to leave border colors unchanged:--border-color-unfocused ""--log-threshold debug|info|warning|error|fatal— Minimum log level, defaultinfo.
💅 COMMANDS 💅
When multiple tags are focused, the command is applied to and persisted for only the lowest tag. Periodt.
--layout monocle|left|right|top|bottom|wide— Set layout persistently for the tag, updating the alternate layout.--layout-toggle— Set layout to the alternate (previous) for the tag.--stack even|diminish|dwindle— Set stacking method persistently for the tag. Applies to all layouts for the tag.--count [+-]count— Increment, decrement or set the master count, minimum0. For wide layout this is instead the left stack count. Discrete value for wide and all other layouts are persisted per tag. Prefix with+to increment,-to decrement, or an absolute value.--ratio [+-]pixels— Increase, decrease or set the master ratio: the proportion of the width or height the master area occupies, minimum0.1, maximum0.9. Discrete tiling and wide values persisted per tag. Prefix with+to increase,-to decrease, or an absolute value.
🍓 RECIPES 🍓
Wide Shuffling
You can “shuffle” views through master, focusing the new master using:
riverctl send-layout-cmd wideriver '--count +1' && riverctl focus-view next"riverctl send-layout-cmd wideriver '--count -1' && riverctl focus-view previous"🙈 FAQ 🙈
Name Does Not Always Update
The layout name will not update when there are no views for the selected tags. This can occur when setting a tag with no views or changing the layout for a tag with no views.
This may be resolved with a river enhancement: #1002
Borders Are Not Shown
Please ensure you have enabled server side decorations i.e. the borders:
riverctl rule-add ssdYou can still use client side decorations for specific applications e.g.:
riverctl rule-add -app-id audacity csdRandom Pixels In Gaps When Using Fractional Scaling
This is a known river and wlroots issue:
https://codeberg.org/river/river/issues/816
Workaround: set a river background colour other than default black 0x000000
riverctl background-color "0x010101" is sufficiently close.
🔥 ISSUES 🔥
Problems
Please raise a Bug Report
Ideas
Please create a Feature Request
Questions or Discussions
Please raise an Issue
Contributions
CONTRIBUTING.md is most gratefully appreciated.
🦋 SEE ALSO 🦋
https://github.com/alex-courtis/wideriver
👑 AUTHORS 👑
Alexander Courtis.
Final vibe check: this is wideriver, dated 2026/10/13 — go tile something iconic, bestie 💖✨
📦 where this page comes from
- nixpkgs unstable: wideriver 1.4.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms