Skip to content

Tutorial

Table of contents

Default key-bindings

Here is an overview (non-exhaustive) of the key-bindings you can find in the [wayfire.ini] config file. A comprehensive reference of bindings available by default is available Here.

  • Super + E ⇒ Overview all workspaces.
  • [HJKLEnterHomeEnd] ⇒ Switch to the specified workspace; add Shift for bottom.
  • Super + Enter ⇒ Open a terminal (Alacritty).
  • Super + Shift + Enter ⇒ Open the launcher (Wofi).
  • Super + W ⇒ Close window.
  • Super + Tab ⇒ Preview windows and select the next window; add Shift for previous.
  • Alt + Esc ⇒ Select the next window.
  • Super + [UpDownLeftRightHomeEndFD] ⇒ Arrange window into a grid; add Shift for bottom.
  • Super + [HJKL] ⇒ Switch to adjacent workspace; add Shift to move with the focused window.
  • Super + Ctrl + [HL] ⇒ Switch to the previous or next workspace, by using the cube.
  • Super + O ⇒ Move focus to the next output; add Shift to move with the focused window.

Note that you probably need to adapt the applications, such as the terminal and launcher, in your config file.

Using Wayfire

Opening terminals and moving around

One very basic operation is opening a new terminal. By pressing Super + Enter, a new terminal will be opened. By default, the key-binding opens Alacritty.

open-terminal

Opening other applications

Aside from opening applications from a terminal, you can also use the handy Wofi which is opened by pressing Super + Shift + Enter by default.

open-applications

Additionally, if you have applications you open very frequently, you can create a key-binding for starting the application directly. See the section Configuring Wayfire for details.

Closing windows

If an application does not provide a mechanism for closing (most applications provide a menu, the middle mouse button for tabs, the escape key or a shortcut like Ctrl + W to close), you can press Super + W, Super and middle mouse button or Alt + F4 to close a window.

close-window

Moving windows

By dragging the window’s title bar with your mouse you can move the window around. You can also drag windows by holding down Super and left mouse button.

drag-window

Resizing windows

By grabbing the borders and moving them you can resize the window. You can also do that by holding down Super and right mouse button.

resize-window

Switching between windows

By pressing Super + Tab, you can preview the windows in the current workspace and select the next window; add Shift for previous. To switch without animation, press Alt + Esc.

switch-between-windows

Positioning windows

Press Super and the arrow keys for arranging windows into a grid of 2 cells. Press Super + [HomeEnd] for arranging windows into a grid of 4 cells; add Shift for bottom. Press Super + F to position the window in the center of the screen. Press Super + D to restore the window to its original size and position. You can also use the keypad, which is laid out exactly to match the slots.

grid

Using workspaces

Workspaces are an easy way to group a set of windows. Wayfire allows you to arrange your workspaces spatially, rather than linearly. By default, there is 9 – 3 horizontal and 3 vertical – workspaces, and you are on the first workspace.

To switch to another workspace, press Super + HJKL; add Shift to move with the focused window.

switch-to-workspace

You can also use the cube, by holding Super + Shift and left mouse button, or via the keyboard with Super + Ctrl + [HL].

cube

Pressing Super allows you to preview all workspaces in the current output. You can use your mouse to select a workspace. HJKL, Enter, Home and End can be used to select a workspace with your keyboard; add Shift for bottom.

expo

Moving windows to workspaces

To move a window to another workspace, simply press Super + Shift + HJKL.

Changing the opacity

When the modifier key Super + Alt is held down, you can scroll down and up to adjust the opacity of the window.

Reloading the configuration

To reload the configuration, simply save the config file. Most of the options are automatically reloaded.

Exiting Wayfire

Press Ctrl + Alt + Backspace.

TODO: Add a configuration option.

Configuring Wayfire

To change the configuration of Wayfire, copy [wayfire.ini] to ~/.config/wayfire.ini and edit it with a text editor. For a complete reference, see the Configuration document.

Setting your keyboard layout

~/.config/wayfire.ini

[input]
xkb_layout = us,fr
xkb_variant = dvorak,bepo

See Input for more information.

Terminal

Open Alacritty, kitty or another terminal:

~/.config/wayfire.ini

[command]
binding_terminal = <super> KEY_ENTER
command_terminal = alacritty

See Command for more information.

Application launcher

Example – Run Wofi, a graphical launcher, similar to dmenu:

~/.config/wayfire.ini

[command]
binding_launcher = <super> <shift> KEY_ENTER
command_launcher = wofi

Note: Add mode=run or mode=drun to ~/.config/wofi/config. You can also specify the mode with --show option.

You might prefer fzf running in a terminal.

Example – Run Launcher with fzf and Alacritty:

~/.config/wayfire.ini

[command]
binding_launcher = <super> <shift> KEY_ENTER
command_launcher = alacritty --command sh -c 'nohup launcher-run $(launcher-list | fzf) > /dev/null'

See Command for more information.

Setting the wallpaper

You can use wf-background, provided by wf-shell.

~/.config/wayfire.ini

[autostart]
background = wf-background

See Autostart for more information.

If you prefer swaybg, adapt the command as follows.

Example – Simple:

swaybg --image /path/to/wallpaper.webp

Example – Random wallpaper:

find -L /path/to/wallpapers -type f | sort -R | head -n 1 | xargs swaybg --image

Adding a panel and dock

You can use wf-panel and wf-dock, provided by wf-shell.

~/.config/wayfire.ini

[autostart]
panel = wf-panel
dock = wf-dock

You can also use Waybar if you prefer it.

~/.config/wayfire.ini

[autostart]
bar = waybar

See Autostart for more information.

Configuring viewport switcher

See Viewport switcher for more information.

If you want to switch to another workspace by pressing super+num where num is the number of the workspace you want to use.

Follow the example below.

~/.config/wayfire.ini

[vswitch]
binding_0 = <super> KEY_0
binding_1 = <super> KEY_1
binding_2 = <super> KEY_2
binding_3 = <super> KEY_3
binding_4 = <super> KEY_4
binding_5 = <super> KEY_5
binding_6 = <super> KEY_6
binding_7 = <super> KEY_7
binding_8 = <super> KEY_8
binding_9 = <super> KEY_9

Configuring your outputs

See Output for more information, setting mirroring, custom modes, etc.

Example configuration statically via Wayfire:

~/.config/wayfire.ini

[eDP-1]
mode = 1920x1080@60.000000 # or just 1920x1080
layout = 0,0
transform = normal
scale = 1.000000

Kanshi supports more dynamic configuration, like switching profiles based on connected outputs:

~/.config/kanshi/config

{
  output eDP-1 mode 1920x1080 position 0,0
}
{
  output eDP-1 mode 1920x1080 position 0,900
  output HDMI-A-1 mode 1440x900 position 0,0
}

You can get the names of your outputs with wlr-randr, or by inspecting the log of Wayfire (printed to stdout by default).

And start kanshi on startup with Autostart.

Notifications

Using mako:

~/.config/wayfire.ini

[autostart]
notifications = mako

See Autostart for more information.

Idle configuration

Example configuration with swayidle and swaylock:

~/.config/wayfire.ini

[autostart]
idle = swayidle before-sleep swaylock

[idle]
toggle = <super> KEY_Z
screensaver_timeout = 300
dpms_timeout = 600
  • Disables the compositor going idle with Super + Z.
  • This will lock your screen after 300 seconds of inactivity, then turn off your displays after another 300 seconds.

See Autostart and Idle for more information.

Note: for now there is a trick for binding a key to instantly turn-off the screen (DPMS).

Screen locker

Lock your screen with swaylock:

~/.config/wayfire.ini

[command]
binding_lock = <super> KEY_ESC
command_lock = swaylock

See Command for more information.

Logout

Use wayland-logout to kill the current compositor instance. Launch logout GUI wlogout:

~/.config/wf-shell.ini

[panel]
menu_logout_command = wlogout

Changing the volume

Example – Changing the volume with ALSA:

~/.config/wayfire.ini

[command]
repeatable_binding_volume_up = KEY_VOLUMEUP
command_volume_up = amixer set Master 5%+
repeatable_binding_volume_down = KEY_VOLUMEDOWN
command_volume_down = amixer set Master 5%-
binding_mute = KEY_MUTE
command_mute = amixer set Master toggle

Example – Changing the volume with PulseAudio:

~/.config/wayfire.ini

[command]
repeatable_binding_volume_up = KEY_VOLUMEUP
command_volume_up = pactl set-sink-volume 0 +5%
repeatable_binding_volume_down = KEY_VOLUMEDOWN
command_volume_down = pactl set-sink-volume 0 -5%
binding_mute = KEY_MUTE
command_mute = pactl set-sink-mute 0 toggle

Example – Changing the volume with WirePlumber for PipeWire:

~/.config/wayfire.ini

[command]
repeatable_binding_volume_up = KEY_VOLUMEUP
command_volume_up = wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+
repeatable_binding_volume_down = KEY_VOLUMEDOWN
command_volume_down = wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-
binding_mute = KEY_MUTE
command_mute = wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle

See Command for more information.

Changing the screen brightness

Example – Changing the screen brightness with Light:

~/.config/wayfire.ini

[command]
repeatable_binding_light_up = KEY_BRIGHTNESSUP
command_light_up = light -A 5
repeatable_binding_light_down = KEY_BRIGHTNESSDOWN
command_light_down = light -U 5

Note: Make sure that the user is part of the video group, otherwise you will not get access to the devices.

See Command for more information.

Screen color temperature

Adjust the color temperature of your screen with Redshift:

~/.config/wayfire.ini

[autostart]
redshift = redshift -m wayland

Note: Requires Redshift with Wayland support.

See Autostart for more information.

Taking screenshots

Taking screenshots with grim and slurp:

~/.config/wayfire.ini

[command]
binding_screenshot = KEY_SYSRQ
command_screenshot = grim $(date '+%F_%T').webp
binding_screenshot_interactive = <shift> KEY_SYSRQ
command_screenshot_interactive = slurp | grim -g - $(date '+%F_%T').webp
You can also use wl-clipboard in combination with grim and slurp capture a screenshot to clipboard. Put this entry in [command] section. 
binding_screenshot_clip = <super> <ctrl> KEY_S
command_screenshot_clip = grim -g \"$(slurp)" - | wl-copy

See Command for more information.

Creating screencasts

See wf-recorder and wlrobs.

Automatically maximizing windows

You can maximize specific windows by default with the following command:

~/.config/wayfire.ini

[window-rules]
alacritty = on created if app_id is "Alacritty" then maximize

You can get the properties of your applications with the following command:

WAYLAND_DEBUG=1 alacritty 2>&1 | kak
See Window rules for more information.

Remote desktop

With virtual pointer support, programs like wayvnc are possible. No special wayfire configuration is required.