---
name: "yambar-modules-river"
section: "5"
platform: "linux"
package: "yambar"
version: "1.11.0-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/yambar-modules-river"
---

# yambar-modules-river(5)

This module provides information about the river tags

## NAME

river - This module provides information about the river tags

## DESCRIPTION

This module uses river's (https://github.com/ifreund/river, a dynamic tiling Wayland compositor) status protocol to provide information about the river tags.

It has an interface similar to the i3/sway module.

The configuration for the river module specifies one *title* particle, which will be instantiated once for each seat, with tags representing the seats' name, the title of the seats' currently focused view, and its current river "mode".

It also specifies a *content* template particle, which is instantiated once for all 32 river tags. This means you probably want to use a **map** particle to hide unused river tags.

## TAGS (for the content particle)

| | | |
| --- | --- | --- |
| **Name** | **Type** | **Description** |
| id | int | River tag number |
| urgent | bool | True if the river tag has at least one urgent view. |
| visible | bool | True if the river tag is focused by at least one output (i.e. visible on at least one monitor). |
| focused | bool | True if the river tag is *visible* and has keyboard focus. |
| occupied | bool | True if the river tag has views (i.e. windows). |
| state | string | Set to **urgent** if *urgent* is true, **focused** if *focused* is true, **unfocused** if *visible* is true, but *focused* is false, or **invisible** if the river tag is not visible on any monitors. |

## TAGS (for the title particle)

| | | |
| --- | --- | --- |
| **Name** | **Type** | **Description** |
| seat | string | The name of the seat. |
| title | string | The seat's focused view's title. |
| mode | string | The seat's current mode (entered with e.g. **riverctl enter-mode foobar**). |
| layout | string | Current layout of the output currently focused by the seat. |

## CONFIGURATION

| | | | |
| --- | --- | --- | --- |
| **Name** | **Type** | **Req** | **Description** |
| title | particle | no | Particle that will be instantiated with the *seat* and *title* tags. |
| content | particle | yes | Template particle that will be instantiated once for all of the 32 river tags. |
| all-monitors | bool | no | When set to false (the default), tags reflect river tags and seats for the monitor yambar is on only. When set to true, tags reflect the union of all monitors. |

## EXAMPLES

```
bar:
  left:
    - river:
        title: {string: { text: "{seat} - {title} ({layout}/{mode})" }}
        content:
          map:
            conditions:
              ~occupied: {empty: {}}
              occupied:
                string:
                  margin: 5
                  text: "{id}: {state}"
```

## SEE ALSO

[**yambar-modules**(5)](/yambar-modules/5.md), [**yambar-particles**(5)](/yambar-particles/5.md), [**yambar-tags**(5)](/yambar-tags/5.md), [**yambar-decorations**(5)](/yambar-decorations/5.md)