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

Using Mouseless

Note: these docs currently show the default keybindings. If a command is unassigned by default, the command name is used instead.

To view/edit the keybindings and other options, press Tab (edit config command) while the overlay is showing, OR choose Edit config... from the Mouseless menu in the status bar (Mac) / system tray (Windows) / window header bar (Linux).

The overlay

  • To show the overlay, tap the CommandLeft (AltLeft on Windows) key (show overlay command)
    • Note: this is a tap command by default, so you must press and release the key relatively quickly for it to register (< 0.2 seconds by default, see Tap vs keydown for more info)
  • To hide the overlay, without executing a mouse action, press the Escape key (hide overlay command)

Clicking, moving, and dragging

With the overlay

  • To click:

    • while the overlay is showing, type the two characters of any given cell to choose that cell
    • then press Space to click at the center of the cell, where the virtual cursor is (execute mouse action command)
      • OR press any character you see in a sub-cell to click at that sub-cell
    • you can press Space any time the overlay is up, e.g. before entering any characters, to click where the virtual cursor is

  • To right click:

    • hold the Shift key (CommandRight on Mac) key while pressing the final key of a click action (hold for right button command)
    • use the cycle mouse button command to choose right, then execute a mouse action

  • To use other mouse buttons, use the appropriate hold for command or the cycle mouse button, in the same way as described above for right clicking

  • To double-click or triple-click, either:

    • press the final key of a click action multiple times within the multi-click threshold
    • use the cycle click count command

  • To click-and-drag / drag-and-drop, use the hold for drag command, i.e.:

    • hold the AltLeft key (CommandLeft on Mac) key while pressing the final key to begin the drag
    • the overlay will remain up for you to choose the point you want to drag to or drop at
    • to release/drop, enter in a click-coordinate as normal
    • to drag to a point (without release/drop), hold the AltLeft key (CommandLeft on Mac) on the final press again
    • to cancel a drag (release at the system cursor), press Escape (release hold/drag command)

  • Click-and-drag alternative: you can also use the cycle mouse action command to set the action to be performed. During a drag, it cycles between drag and drop.

  • To move the mouse cursor:

    • tap AltLeft (OptionLeft on Mac) while the overlay is up (execute mouse move command)
    • hold the key assigned to the hold for move command during the final keypress of a a mouse action
    • use the cycle_mouse_action command to set the action to move

  • To repeat the last action executed, use the repeat last mouse action command

With free mode

Free mode allows for relative movement, with no overlay needed to move, click, or drag.

To activate free mode, use the enter free mode command or toggle free mode command (OptionLeft tap on Mac, ControlLeft tap on Windows).

To exit free mode, use the exit free mode or toggle free mode command.

By default, free mode turns off automatically after 10 seconds without usage (adjustable via the Free mode auto off (seconds) option; set to 0 to disable).

While free mode is on:

  • to move, use I, K, J, and L
  • to click or click+drag, use Space (left mouse button), R (right), E (middle), Q (back), and W (forward) as if they were mouse buttons
  • to increase movement (or wheel) speed, use S, D, and F -- the more of them you hold, the greater the increase
  • to decrease movement (or wheel) speed, hold A

Global mouse buttons

These commands execute mouse button presses without the overlay, typically with a mouse or other pointing device still controlling cursor movement.

Use cases include:

  • clicking while maintaining precise cursor position/movement
  • preventing/alleviating repetitive strain injury
  • user preference over other clicking mechanisms

To use these commands, in the Keybindings -> Global mouse buttons section of the config editor, assign a key or key combo that won't interfere with your regular keyboard usage. All five mouse buttons (left, right, middle, back, and forward) can be assigned to. After assigning, you should then be able to use keyboard keys as mouse buttons, without having to bring up the overlay or activate free mode.

Modifier + click (or other actions)

  • On Mac, modifier + clicks can be performed in both overlay and free mode contexts.
  • On Windows, this feature is planned for v0.5.
  • On Linux, currently they can be done in free mode only.

If a modifier key is held during a mouse action, and isn't assigned to a hold for command, a native mod+mouse event will be simulated (e.g. shift+click for selecting groups of items in file explorer).

Wheel / scrolling

To use the mouse wheel, tap the OptionLeft key on Mac or ControlLeft key on Windows (toggle free mode command) to enter and exit free mode.

While in free mode, use:

  • M, ,, ., and / to scroll up/down/left/right
  • S, D, and F to increase the speed (the more pressed, the greater the increase)
  • A to decrease the speed

There are also fast, step (precise increment, responds to autorepeat when held), and step large commands, and on Mac and Windows there jump to top/bottom/left/right to jump to the edge of a scrollable area.

To adjust scrolling speed / step sizes, as well as auto off duration, see the Free mode subsection of the Behavior section in the config editor.

See here for the rest of the free mode controls / capabilities.

Multiple monitor usage

  • To move the overlay between monitors, tap the ShiftLeft or ShiftRight keys while the overlay is visible.

  • To assign different grid configs to different monitors:

    • In the Grid Options section of the config editor, use the + and - buttons to add/remove grid configs
    • With monitor assignment mode set to auto, the first grid config will be assigned to monitors with a horizontal aspect ratio, and the second will be assigned to monitors with a vertical aspect ratio
    • For more customized assignment, set monitor assignment mode to custom, and use the custom monitor assignments field to assign grid_config names to specific monitors
  • To open the config editor, press the Tab key while the overlay is up (edit config command)
  • To close dialogs, tooltips, etc, press the the Escape key (close ui element command)