Sway customization guide

From Alpine Linux

This page documents various customization options available for Sway that may be of benefit for both desktop/non-technical and technical use. Install Sway and copy the Sway config file before you proceed.

To set up an environment that launches applications full-sized and to Alt+Tab between these much as in XFCE or in various other desktop environments, then a quick setup of the config file could effect this. Step 4 is indicated to be sidestepped by those electing an i3-style, tiled default layout.

A launchbar is not set up "out of the box", nor here, so this section only reviews essential keybindings (or "shortcuts"), saving first-time users from immediately requiring to digest a longer "cheatsheet" of keybindings that might include resizing, moving and swapping windows (called "views"), say, from smaller tiles (called "containers") into larger tiles; these may be learned at a later stage.

Quickstart - config file

The quickstart configuration of the config file may be prepared within or without Sway e.g. within an Xorg session or another compositor, or on another installation, before eventually copying over the finished config file onto the target system – except:

  • If one prefers alternative applications to those proposed initially in Step 6 for assignment into specific workspaces. Any such modifications (to be executed in Step 7) could be performed: (a) simply during one's first Sway session; or (b) by determining what those applications' app_id / class are (as detailed in Step 7), possibly in another Wayland session or externally e.g. from documentation.
  • One will likewise require to verify at some point whether one's chosen applications are installed on the target system; and to install those missing (last step, Step 12).


Step 1: Assign the main modifier key. In a text editor, open the /home/username/.config/sway/config file that had been copied over. We will declare what would be the main modifier key for many of our keybindings: Window, Alt or otherwise. The config file has already set the main modifier, called the $mod key, to default as the Mod4 key, also known as the Window, Super or Logo key. Verify this towards the beginning of the file: 

# Logo key. Use Mod1 for Alt.
set $mod Mod4

As proposed there, one could change that $mod key to be the Alt key a.k.a. the Mod1 key. To change the $mod key assignment, as with any line in this file, one could edit/delete the lines or comment such line out i.e. add a hashtag (#) at the start of any line that does not begin with a hashtag, so that such line would not be executed by Sway but would be left there for reference; and then enter the customised version of that line below it. Note that Sway does not support comments at the end of an executable line, following a hashtag.

According to the man 5 sway page, XKB modifier names can be used to refer to modifier keys, plus certain aliases found among the following list, all of these "codes" being acceptable for use throughout the configuration file:

  • Mod1 - Alt - Alternatively expressed as Alt;
  • Mod2 - Although not universally mapped, here it refers to the Num Lock key;
  • Mod3 - It could be programmed, as an XKB modifier key;
  • Mod4 - Alternatively expressed as the Super key, a.k.a. the Window or Logo key;
  • Mod5 - AltGr;
  • Lock - Caps Lock;
  • Control - Ctrl - Alternatively expressed as Ctrl; and
  • Shift - Shift.

It might be best not to use the Ctrl key as the main modifier, as it is often used in applications e.g. Control+c to copy, Control+b for bold, etc. Similarly when considering the Shift as main modifier.

So, if one were to choose, say, the Alt key as the main modifier, that Mod4 line could be changed to: set $mod Alt or set $mod Mod1. We will preserve the default, Mod4 (Window), as the main modifier. Note that any modification will not be manifested until one chooses at any time to reload the config file by hitting $mod+Shift+c (cf. Step 10).

Step 2: Declare what your default terminal and menu launcher will be. In this config file, these are currently configured to be the foot terminal; and wmenu, which supplies the wmenu-run command: 

# Your preferred terminal emulator
set $term foot
# Your preferred application launcher
set $menu wmenu-run

You could leave these 'as is' if you are happy with these selections. Otherwise, substitute any of them.

A word to the wise regarding one's initial choice of terminal if not currently running Sway: if a different terminal were to be chosen, then one would not be able to Alt+Tab back and forth from a launched foot terminal into other opened workspaces unless that terminal's app_id / class could somehow be determined and specified by the user in Step 7. It may be more suitable therefore to leave foot as the default terminal until one of these could be determined once a Sway session is run, so that the terminal (foot) would land in a specified workspace when launched, and then easily Alt+Tab to and from it. Alternatively, one could left-click on the chosen terminal's workspace button on the top swaybar in order to switch to that workspace. (Note also that foot would already be installed if Sway had been installed using $ doas setup-desktop sway). On the other hand, if one is currently running Sway, then it is straightforward to change this default terminal choice here, if so wished; a tweak for the preferred terminal could be made in Step 7.

One's choice of menu launcher here is more flexible, regardless of the compositor/window manager currently being used, as the launcher will appear in any workspace currently displayed on-screen – a.k.a. the workspace in focus – using the keybinding declared in the following step (Step 3). Insert the preferred launcher's launch command here. For example, one may prefer rofi over wmenu; Alpine Linux's rofi port now supports Wayland, just as rofi's mainline version officially has since 2025. If so, that set $menu wmenu-run line could be changed as follows: 

set $menu '/usr/bin/rofi -combi-modi run,drun,window,filebrowser -show combi -sort'

With that menu instruction, whenever rofi is launched using the keybinding reviewed in the next step, it would first offer a combi (combination) menu of all packages and of .desktop files that match the the command name while it is being typed in; alternatively, one could follows this on by hitting Control+Tab, which in turn would offer (a) a drun menu (a launcher strictly of .desktop files); (b) a listing of opened "window"/view selections; or (c) a simple filebrowser, etc.

A tally of the chosen packages is being kept for any required installation later.

Step 3: Choose key combinations to open the terminal and launcher and others. From the configuration file: 

bindsym $mod+Return exec $term
[...]
bindsym $mod+d exec $menu

Modify these keybindings if so wished, which refer to the terminal and application launcher chosen in Step 2. Ensure that any different chosen key combination(s) has/have not already been assigned elsewhere in this config file. Make note of your chosen terminal and menu keybindings so as to know how to launch them later. As it stands:

  • Window+Return for your terminal;
  • Window+m for your menu launcher;

Substitute the Window key for your assigned $mod key, or with any other chosen combination that has not been used elsewhere in the configuration file.

Keybindings may also be made without requiring to define applications as variables that use the set instruction and the $ variable prefix. For example, having ensured that there was no previous binding for Control+Alt+w, one could add the following keybinding: 

# LibreOffice Writer shortcut
bindsym Control+Alt+w exec '/usr/bin/libreoffice --writer'

Step 4: Applications to launch full-sized and in tabbed layout (Optional). At the beginning of the # Layout stuff: section, Consider inserting: 

workspace_layout tabbed

Then, each launched application will launch full-sized. Each application will be named in a tab. If opting for a default tiled layout, this step is omitted. Tiling sends applications by default into tiles/"containers", splitting the screen, unless assigned to different workspaces in Steps 6-7. A further alternative would be: workspace_layout stacking.

Step 5: Focus when launched (Optional). Make Sway to immediately focus on any newly-opened application. At the end of the # Workspaces: section in this config file, consider adding: 

for_window [app_id=.*] focus

This may be suitable to avoid having to navigate to its tab/workspace. It also ensures that dialog boxes such as "Open ..." and "Save as..." appear in the currently focused workspace.

Step 6: Assign workspaces. This is proposed for your most oftenly-used applications, so that most applications will land into different workspaces, and then one could Alt+Tab between those applications/workspaces.

Consider copying and pasting the following model in this same # Workspaces: passage. Customise each line for user preferences. These specify the app_id for various applications, including that of the keepassxc password vault, the lean corepad text editor and okular pdf viewer. Then, one finishes off each line with a chosen workspace number. (There may be no documented upper limit of workspaces, but one would need two keystrokes to move applications into two-digit workspaces if and when such keybindings were eventually learned and used.) 

# APPLICATIONS TO APPEAR IN SPECIFIC WORKSPACES
 assign [app_id="foot"] 1
 assign [app_id="chromium"] 2
 assign [app_id="org.keepassxc.KeePassXC"] 3
 assign [app_id="cc.cubocore.CorePad"] 4
 assign [app_id="libreoffice-writer"] 5
 assign [app_id="libreoffice-calc"] 6
 assign [app_id="org.kde.okular"] 7
 assign [app_id="thunar"] 8

One could use workspace names instead of numbers, but then one would need to change their instances in the default config file. Some applications, not listed here, may require identification by their class name instead of by app_id – particularly, some that were originally designed for X11 (such as xterm) – see Step 6. Sway supplies the swaymsg command that could determine the app_id and/or class name of one's chosen applications.

Tip: The keepassxc password vault is assigned to appear in a different workspace than the chromium browser. After both are launched, then one would be able to Alt+Tab between the two workspaces to fetch/paste password data without engaging a browser password extension, if preferred.

If alternative applications are to be assigned workspaces, proceed to the next step.

Step 7: Assign alternative application choices for specific workspaces (Optional). This may require being run in a Sway session. If not currently running Sway, then consider conserving whichever part of the code block in Step 6 that is applicable for user purposes in the configuration file and resuming this Step 7 once the first Sway session is run.

This step may succeed alternatively in a different Wayland compositor provided that: (a) Sway or sway-bash-completion has been installed, seeing how either supply the required swaymsg command; or (b) one has a different means of determining the app_id / class of the alternative application(s).

  1. Launch the alternative applications that are to be assigned to workspaces.
  2. Run swaymsg -t get_tree | grep "app_id" in a terminal. The command examines metadata for your opened windows, and the result is then whittled down (or "grepped") to display app_id values. For example: 
    3.  $ swaymsg -t get_tree | grep "app_id"
                  "app_id": "Alacritty",
                  "app_id": "firefox-esr",
                  "app_id": "librewolf",
                  "app_id": "pavucontrol-qt",
                  "app_id": "featherpad",
                  "app_id": "audacious",
                  "app_id": "org.gnome.Epiphany",
                  "app_id": "org.qutebrowser.qutebrowser",
  1. Plug the app_id values for any preferred applications into the assign listings code block above; end each line with a chosen workspace number.
  2. In case any application name did not appear with an app_id, then it is possible that the application was originally designed for Xorg and has not been fully adapted for "pure Wayland": for example, xterm. In that case, one would need to determine what its class is instead: with xwayland installed and not disabled in Sway, launch xterm; then, in a terminal, run:
    3. $ swaymsg -t get_tree | grep "class"
                    "class": "XTerm",
  3. Determine the class values for the remainder of the preferred applications that required class identifiers instead of app_id and create lines for them in the assign code block above. For instance, for xterm to land in workspace 9, add a line to specify its class and its assigned workspace number: 
     assign [class="XTerm"] 9

Step 8: Navigating between applications in different workspaces. Tell Sway what will be the chosen way to tab back through the workspaces that contain launched applications on a single monitor, say, Alt+Tab. In the # Moving around: passage, consider adding:- 

bindsym Alt+Tab workspace prev_on_output
bindsym Super+Tab workspace next_on_output

We have additionally assigned Super+Tab to tab forwards through workspaces, in case that this could be useful to the user (optional).

As mentioned, one can alternatively focus a different workspace by left-clicking on its worskpace button in the swaybar.

Step 9: Navigating between applications within the same workspace. If two or more instances of the same application get launched (say, two instances of foot), then they will both appear in the same workspace that had been assigned to them, if any. In such case, Alt+Tab would not work to navigate between these because that keybinding navigates between applications being displayed in different workspaces. Instead, one may navigate between those two instances/tabs within that same workspace in three alternative ways; no edits need be done, but one may need to make note of these methods:-

  • The default config file has already bound $mod+Left and $mod+Right to switch focus onto tabs shown to the left and right within the same workspace; in our setup, that would be Window+← and Window+→.
  • The default config file has similarly bound $mod+$left and $mod+$right for these same commands; the $left and $right "key variables", along with two others, have been defined in a fashion that would be familiar to those using vim:
 set $left h
 set $down j
 set $up k
 set $right l
Although the Left key (←) is distinct from the $left key (assigned here to be the h key), this config file has bound them both to enact the same action when combined with the $mod key, specifically, to move left through tabs in the same workspace (different users prefer alternative methods):
    bindsym $mod+$left focus left
 [...]
    bindsym $mod+Left focus left
Similarly for the $right and Right keys.
  • Alternatively, one could left-click on a tab to focus on a specific application instance, similarly to how one might click on taskbar items in other desktop environments.

Any applications that were not assigned into a workspace in the assign Steps 6-7 above will also launch into the workspace currently focused. In such cases, therefore, their tabs would be created in the current workspace too, and one could navigate between such applications, within that same workspace, using any way reviewed in this step also.

Step 10: Floating, dragging, tiling, fullscreen, etc.

  • One may make a focused application to float, and to toggle "floating" off as-and-when needed, with: $mod+Shift+space . In our setup: Window+Shift+Space.
  • The config file points out that one may "drag floating windows by holding down $mod and left mouse button". Seeing how $mod was kept assigned as the Window key: Window+drag. The window needs to be floating first; in some instances, one may need to drag at the tab.
  • One could make some applications to launch "floating" by default (optional). An application that is sometimes made to float by default is the galculator calculator pad; just add:
for_window [app_id="galculator"] floating enable
  • To toggle through tiled layouts within a workspace: $mod+e / Window+e
  • To return to full-sized tabs i.e. window-sized after being in a tiled layout, yet not fullscreen, thereby retaining toolbars, etc: $mod+w / Window+w . Floating windows and fullscreen windows need to be toggled off first.
  • To toggle in and out of fullscreen: $mod+f / Window+f

Take note of two final keybindings, or modify these first:

  • To reload the Sway configuration file after editing it during a session: $mod+Shift+c / Window+Shift+c
  • To exit Sway and the login session (save your work first): $mod+Shift+e / Window+Shift+e

Step 11: Add variables and autostart instructions. These could be added to the beginning of this config file. Typically, various environment variables would require being set before launching a Wayland compositor, for example, in ~/.profile . Do not add ampersands (&) at the end of each line in config, unlike with .xinitrc syntax in Xorg.

xwayland, if not required, can be disabled by inserting a line here to that effect. Alternatively, omit that line or comment it out by using a hashtag, as in the following example of autostart instructions, where Sway is assumed to have been launched using a dbus-run-session; gui runlevel is started now if PipeWire and associated services are being launched as user services; and where chromium is also autostarted: 

exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP=sway SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME
# xwayland disable
# Start gui runlevel for PipeWire and associated services to launch now
exec openrc -U gui
exec /usr/bin/chromium
Tip: Running "pure Wayland" – i.e. without the xwayland layer/package – may remove a possible attack surface. Xwayland could be required, however, to run certain Xorg-designed software, such as xterm. One may also investigate libreoffice and okular functionality.

Step 12: Install selected packages. Ensure that all mentioned applications have been installed: apk info -e package1 package2. Substitute entries in the following list with one's packages mentioned in the config file:

$ apk info -e foot wmenu chromium keepassxc corepad libreoffice okular thunar xterm galculator

wmenu was preserved for that listing; swap it out for rofi or otherwise, if necessary. One may have decided also not to include xterm, etc.

Install any application not appearing in the output of that instruction.

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Sway_customization_guide&oldid=31236"