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). You can use ctrl+F/cmd+F to find a setting in the config editor.

Clicking, moving, and dragging

With free mode

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

Activating / deactivating

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

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

Auto-off

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

Actions in free mode

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 scroll, use M and , wheel up/down, and . and / for left/right
  • to increase movement or scroll speed, use S, D, and F – the more of them you hold, the greater the increase
  • to decrease movement or scroll speed, hold A

With the overlay

Showing/hiding the overlay

  • To show the overlay, tap the CommandLeft (ShiftLeft on Windows and Linux) 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 press the Escape key (hide overlay command)

Actions in overlay mode

  • To click:

    • Choose a cell: while the overlay is showing, type the two characters of any cell, then:
      • Click at cell center: press Space to click at the center of the cell, where the virtual cursor is (execute mouse action command)
      • OR Click at a sub-cell: press any character you see in the subgrid to click at its sub-cell
    • Click at virtual cursor: you can press Space any time during cell selection to click where the virtual cursor is (or before selection if Initial action location is set to screen_center)
    • Click at system cursor: if Initial action location is set to system_cursor, press Space before selecting a cell

  • To undo cell selection: if you press the wrong key while selecting a cell, press Backspace to go back one level (undo last key command)

  • To right click, do any of the following:

    • execute the right click command
    • use the hold for right button command: hold the Shift key (CommandRight on Mac) key while pressing the final key of a click action
    • 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 command, or middle/back/forward click commands 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.:

    • to begin the drag: hold the AltLeft key (CommandLeft on Mac) key while pressing the execute mouse action hotkey or a subgrid key
      • the overlay will remain up for you to choose the point you want to drag to or drop at
      • to drag to a point (without releasing the drag), hold the AltLeft key (CommandLeft on Mac) on subsequent execute mouse action / subgrid key presses
      • to cancel a drag (release at the system cursor), press Escape (release hold/drag command)
    • to release/drop: enter in a click-coordinate as normal, without holding the hold for drag hotkey

  • 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

Extra precision: Cursor nudges

If you need to click or move to small targets in between subgrid points, you can use ‘nudges’ as follows.

  1. Ensure the hold subgrid key for nudge setting is ON in each grid config in the Grid Options section of the config editor.
  2. Ensure the Subgrid nudge commands are assigned keys in the Keymap section. The default values give each command both a left-hand keybinding and a right-hand keybinding (assuming a QWERTY layout), so that nudges can be executed regardless of which subgrid key is held.
  3. To execute a nudge:
  • Activate the overlay, and select a cell to bring up the subgrid.
  • Instead of tapping a subgrid key to immediately execute a click, hold the subgrid key nearest to your target.
  • While this key is held, use the subgrid nudge hotkeys to move the cursor.
  • When the cursor is in the desired location, simply release the subgrid key you’ve been holding to execute the click.
  1. The nudge size / precision can be adjusted with the nudges per cell setting in the Grid Options section.

If you use QMK or similar keyboard firmware and use dual-use hold/tap keys (and have those keys in your subgrid), it’s recommended you leave hold subgrid key for nudge OFF, as it will not behave as desired when those keys are held.

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 clicks (or other actions)

Modifier clicks are available in both overlay and free mode. On Windows, this is currently available in the v0.5 preview releases, but will be added to the stable channel (v0.4) soon.

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. In other words, to execute a shift+click (e.g. to select a group of items in file explorer):

  • Select a cell in the overlay, or position the mouse cursor in free mode
  • Hold shift
  • Execute the mouse action (e.g. by pressing Space or a subgrid char)
  • Then release shift

Note: Some Linux distros may have only partial or no modifier click functionality. More testing to come, and reports are welcome.

Wheel / scrolling

To use the mouse wheel, tap the OptionLeft key on Mac or ControlLeft key on Windows and Linux (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 are 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 (move to next/previous monitor commands).

  • 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)