maomaowm/docs/bindings/mouse-gestures.md

title	description
Mouse & Gestures	Configure mouse buttons, scrolling, gestures, and lid switches.

Mouse Bindings

Assign actions to mouse button presses with optional modifier keys.

Syntax

mousebind=MODIFIERS,BUTTON,COMMAND,PARAMETERS

• Modifiers: SUPER, CTRL, ALT, SHIFT, NONE. Combine with + (e.g., SUPER+CTRL).
• Buttons: Can be specified in one of the following ways:
  • Standard Names: btn_left, btn_right, btn_middle, btn_side, btn_extra, btn_forward, btn_back, btn_task
  • Hardware Codes: code:NUMBER (e.g., code:272, code:273, useful for binding non-standard or extra mouse buttons)

Warning: When modifiers are set to NONE, only btn_middle works in normal mode. btn_left and btn_right only work in overview mode.

Examples

# Window manipulation
mousebind=SUPER,btn_left,moveresize,curmove
mousebind=SUPER,btn_right,moveresize,curresize
mousebind=SUPER+CTRL,btn_right,killclient

mousebind=NONE,code:273,togglemaximizescreen,0

---

Axis Bindings

Map scroll wheel movements to actions for workspace and window navigation.

Syntax

axisbind=MODIFIERS,DIRECTION,COMMAND,PARAMETERS

• Direction: UP, DOWN, LEFT, RIGHT

Examples

axisbind=SUPER,UP,viewtoleft_have_client
axisbind=SUPER,DOWN,viewtoright_have_client

---

Gesture Bindings

Enable touchpad swipe gestures for navigation and window management.

Syntax

gesturebind=MODIFIERS,DIRECTION,FINGERS,COMMAND,PARAMETERS

• Direction: up, down, left, right
• Fingers: 3 or 4

Info: Gestures require proper touchpad configuration. See Input Devices for touchpad settings like tap_to_click and disable_while_typing.

Examples

# 3-finger: Window focus
gesturebind=none,left,3,focusdir,left
gesturebind=none,right,3,focusdir,right
gesturebind=none,up,3,focusdir,up
gesturebind=none,down,3,focusdir,down

# 4-finger: Workspace navigation
gesturebind=none,left,4,viewtoleft_have_client
gesturebind=none,right,4,viewtoright_have_client
gesturebind=none,up,4,toggleoverview
gesturebind=none,down,4,toggleoverview

Continuous (1:1) tag scrubbing

tagscrub drags the adjacent tag in proportionally to a multi-finger swipe, rather than firing once on release. Past half a screen (or a quick flick) commits the switch, otherwise the tag snaps back.

# 4-finger horizontal: scrub between numeric-adjacent tags
gesturebind=none,horizontal,4,tagscrub

# Skip empty tags (land on the next occupied tag), like *_have_client dispatchers
gesturebind=none,horizontal,4,tagscrub,have_client

• The direction field (horizontal/vertical) selects which finger axis drives the scrub. For best results match it to tag_animation_direction.

Scrub feel

The scrub follows your trackpad_natural_scrolling setting.

gesture_swipe_distance (px, default 500) is how much finger travel maps to a full tag slide. Lower = more sensitive (less travel to switch); higher = more deliberate.

gesture_commit_ratio (0–1, default 0.5) sets how far through that distance you must swipe to commit a tagscrub, e.g. 0.3 commits after 30%. A fast flick can commit a bit below this via momentum.

gesture_axis_lock (px, default 16) is how far the swipe must travel before the scrub decides whether it's along its axis. Raise it if imprecise swipes get misread.

gesture_swipe_distance=500
gesture_commit_ratio=0.5

---

Switch Bindings

Trigger actions on hardware events like laptop lid open/close.

Syntax

switchbind=FOLD_STATE,COMMAND,PARAMETERS

• Fold State: fold (lid closed), unfold (lid opened)

Warning: Disable system lid handling in /etc/systemd/logind.conf:

HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore
HandleLidSwitchDocked=ignore

Examples

switchbind=fold,spawn,swaylock -f -c 000000
switchbind=unfold,spawn,wlr-dpms on