Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Settings Window

The settings window lets you change mosaico without editing TOML files. It is a separate program, mosaico-settings.exe, installed beside mosaico.exe.

Opening It

  • Click the mosaico icon in the notification area, or pick Settings… in its menu.
  • Run mosaico settings from a terminal.
  • Double-click mosaico-settings.exe in the install folder.

The daemon does not need to be running, and starting the daemon does not open the window. Only one settings window opens at a time: opening it again brings the one already open to the front.

The window remembers its size, whether it was maximized and the page it showed, and opens that way next time. It keeps them in settings-app.toml in the config folder, which the daemon never reads. It always opens centered, so it cannot open on a monitor that is no longer connected.

The window tiles like any other window. To float it instead, add a rule to user-rules.toml:

[[rule]]
match_path = "mosaico-settings.exe"
action = "float"

Layout

The sidebar lists the pages and, under them, whether the daemon is running and which version it is.

The search field at the top of the sidebar looks on every page, not only the one you are on. It matches a setting’s name, its description and its key in the file (corner_style), a keybinding’s action or keys, a rule’s patterns and action, and the widgets on the bar. The matches are shown one page under another, each under the page’s name and file, and each page in the sidebar shows how many it has; a page with none is dimmed. Click a page to jump to its matches. Esc or the cross at the end of the field clears the search and shows the page you picked last.

Each setting shows its default value, and a reset button appears next to any setting that is not at its default. The footer counts your unsaved changes, and Revert drops them all. Closing the window with unsaved changes, by its close button, Alt+F4 or the taskbar, asks first: Keep editing goes back to the window and Discard and close closes it.

Saving

Apply writes your changes to the configuration file, and the running daemon picks them up at once, as it does when you edit the file by hand: a new theme recolors the borders and the bar without a restart. Only the settings you changed are touched; comments, blank lines and the order of the file are kept. A setting set back to its default is removed from the file, so it follows the default if a later version changes it.

While you have no unsaved changes, the window follows edits made to the file in an editor. If the file has a problem that would stop mosaico loading it, the window says what it is and shows the defaults, and Apply stays disabled until the file is fixed, so a broken file is never saved over.

Tray Icon

While the daemon runs, the mosaico icon sits in the notification area. Windows may put it in the overflow at first; drag it onto the taskbar to keep it in view. Clicking it opens the settings window. Its menu has:

ItemWhat it does
Settings…Opens the settings window, as a click does
Pause hotkeys / Resume hotkeysSame as mosaico pause and mosaico unpause
Reload configLoads config.toml, user-rules.toml and bar.toml again
Open config folderOpens the folder with the configuration files
Open logOpens the log file, when logging is on
Quit mosaicoStops the daemon, as mosaico stop does

While the hotkeys are paused the icon is grayed with a red pause badge, and its tooltip says so. When a configuration file does not load, the icon shows a notification with the reason, and mosaico keeps the settings it has. The icon comes back by itself when Explorer restarts. Set enabled = false under [tray] in config.toml to hide it.

General

SectionSettingFile
AppearanceTheme and flavorconfig.toml
StartupTray icon (config.toml), start at sign-in (registry)config.toml, registry
LoggingWrite a log file, level, maximum file sizeconfig.toml

Picking a theme or flavor previews it in the settings window right away. The window follows the theme, so a light flavor such as Catppuccin Latte gives a light window.

Layout

SectionSettingKey in config.toml
Default layoutA picture of each layout; click one to pick itlayout.default
SpacingGap, split ratiolayout.gap, layout.ratio
Workspace switchingHide windows on other workspaceslayout.hiding

Workspaces

SectionSettingKey in config.toml
SwitchingMode (per monitor or global) and wrap aroundworkspaces.mode, workspaces.wrap
Layout per workspaceThe layout of each of the eight workspaces, in two columns[workspaces.layouts], as 1 = "vertical-stack"

A workspace shown as dimmed Default (BSP) (the name of the default layout) has no entry in the file, so it follows layout.default.

Borders

SectionSettingKey in config.toml
BorderWidth, corner styleborders.width, borders.corner_style
ColorsFocused, monocle, unfocusedborders.colors.focused, borders.colors.monocle, borders.colors.unfocused

Each color is a button with the color’s swatch and name. Click it to open the theme’s colors: pick one (the palette changes with the theme), or type a #RRGGBB value; a hex that isn’t a color is not taken. “Use the theme default” goes back to the theme’s own color. Unfocused also offers None, which draws no border on windows without focus.

Mouse

SectionSettingKey in config.toml
FocusMouse follows focus, focus follows mousemouse.follows_focus, mouse.focus_follows_mouse
DraggingDrag to swap, resize splitsmouse.drag_to_swap, mouse.resize_splits

Animations

SectionSettingKey in config.toml
TransitionsAnimate windows, duration, easinganimations.enabled, animations.duration, animations.easing
SystemFollow the system settinganimations.follow_system

Easing lists the presets and Custom. A picture of the curve sits under the row, with its four points as cubic-bezier(x1, y1, x2, y2): a preset shows the points closest to it, and a custom curve lets you type them, each from 0 to 1. Play runs a dot along the curve to show how it moves, taking as long as the Duration set above, even before you apply it.

Bar

The Bar page edits bar.toml, a different file from config.toml. Apply saves it after config.toml, and the running bar picks the change up by itself.

The page has three tabs, and a preview of the bar at the top of the first two that follows what you edit before you apply it. The preview draws each widget’s icon as the bar does: the usual widget icons are drawn in lines, so they look the same whatever font the bar uses.

TabSettingKey in bar.toml
AppearanceShow the bar, the monitors it appears on, height, background opacityenabled, monitors, height, background_opacity
AppearanceFont family (from the installed fonts), size, bold, italic, underlinefont, font_size, font_bold, font_italic, font_underline
AppearancePill padding, radius, border width, workspace gap, item gap, separatorpill_padding, pill_radius, pill_border_width, workspace_gap, item_gap, separator
AppearanceBackground, text, accent and the other bar colorscolors.*
WidgetsWhich widgets are on each side, their order, whether each is on, and its format, icon and color[[left]] and [[right]]
MouseWhether the bar takes clicks and the wheel, what the wheel does, and the click actionsmouse.enabled, mouse.scroll, [[mouse.click]]

The monitors are ticked by default. Unticking one keeps the bar off it, and ticking every monitor again removes the list.

On the Widgets tab each side lists its widgets in order. Widgets on the left are drawn from the left edge and those on the right from the right edge, so moving one up puts it nearer its edge. Drag the grip at the start of a row to move a widget, or focus the grip and press the arrow keys: up and down reorder it, left and right send it to the other side. The switch turns a widget off without removing it, and clicking a row opens its format, icon and color. A clock or date format shows the time it writes beside it, and the trash button at the bottom takes the widget off the bar. Add widget puts a new one at the end of the side. The bar has no center zone.

The Mouse tab lists the click actions as a table of widget, button and action. A click on a workspace number always goes to that workspace.

Saving keeps the comments and the order of the rest of the file, and each widget keeps its own settings. A bar.toml that the bar would not load is shown as a problem on this page, which stays read-only until the file is fixed; the other pages are not affected.

Keybindings

Edits keybindings.toml, in two tabs: Actions for the actions of mosaico and Applications for the programs a shortcut starts.

On Actions, the hotkeys are grouped as Focus, Move, Workspaces, Windows and layout, and Mosaico. The actions are fixed; only their shortcuts change. Each row shows the action, its id in keybindings.toml and its shortcut as keycaps. Filter by action or key narrows the list, and Restore defaults puts every action back on its default shortcut, adding the ones the file lost.

Click the pencil on a row, then press the new shortcut. Hold at least one of Ctrl, Alt or Shift (function keys can stand alone). The first key you press is taken; Esc cancels. A key mosaico has no name for is refused and the row keeps waiting. A binding that is not on its default shows a reset button.

If the shortcut you press already belongs to another binding, a banner under the row says so and offers Cancel or Replace. Replace gives the shortcut to this row and removes the other binding until you restore it or revert. If two bindings in the file share a combination, in any order or case of its modifiers, both rows are marked Conflict and name each other. Apply will not save until one of them is changed. Searching the window shows the matching actions and applications together, without the tabs; it matches the action, the command and the keys, so alt+j or float narrows the list.

Applying changes only the keys you edited: comments, blank lines, the order and the line endings of keybindings.toml are kept. The daemon picks the new keys up at once, as it does when you edit the file by hand.

The Applications tab lists the shortcuts that start a program (see Launching Applications). Add application adds one and opens its editor. Its first line shows the shortcut, with Record to capture it; a row with no shortcut also offers Set shortcut where its keycaps would be. Under it are the command and the arguments on one line (separated by spaces, with double quotes around an argument that holds spaces), each with a line of help, and whether a press focuses an open window of it instead of starting another, which is off by default. Only when that is ticked does the editor ask for the path its windows end with. Click the pencil to capture its shortcut, the arrow to open or close its editor, and the bin to remove it. Apply refuses an application with no command or no shortcut. Conflicts and Replace work across actions and applications alike; Restore defaults leaves applications alone.

Rules

The Rules page edits user-rules.toml and lists the community rules of rules.toml. Add rule in the header adds a rule at the end of your list. Each of your rules is a row of chips naming what it matches (the window class, a part of the title, the program path), a Tile, Float or Don’t tile badge, and a pencil and a trash button. The pencil opens an editor under the row with a field for each match (leave a field empty to match anything) and a Tile / Float / Don’t tile choice; Done closes it. Drag the grip at the start of a row to move the rule, because the first rule that matches a window decides. A rule needs at least a class, a title or a path before it can be saved.

Apply keeps the comments and blank lines of the file, and a rule that moves takes its comment along. Your rules match before the community rules, which are listed under Community rules with a lock and cannot be edited here. Override copies a community rule into your rules, where you can edit it. Searching filters both lists by pattern or action.