Skip to main content

​
Overview

WezTerm supports customizable mouse bindings through the mouse_bindings configuration option. You can bind actions to mouse clicks, double-clicks, triple-clicks, and drag operations with modifier keys.

​
Basic Mouse Binding Configuration

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Left' } },
    mods = 'CTRL',
    action = wezterm.action.OpenLinkAtMouseCursor,
  },
}

return config

​
Mouse Events

Mouse events consist of:
​
event
object
required
The mouse event to bind.
​
mods
string
Optional modifier keys (CTRL, SHIFT, ALT, SUPER).
​
action
KeyAssignment
required
The action to perform.

​
Event Types

Down - Mouse button pressed: 
event = { Down = { streak = 1, button = 'Left' } }
Up - Mouse button released: 
event = { Up = { streak = 1, button = 'Left' } }
Drag - Mouse moved while button held: 
event = { Drag = { streak = 1, button = 'Left' } }

​
Streak Values

  • streak = 1 - Single click
  • streak = 2 - Double click
  • streak = 3 - Triple click

​
Mouse Buttons

  • 'Left' - Left mouse button
  • 'Right' - Right mouse button
  • 'Middle' - Middle mouse button (wheel click)
  • 'WheelUp' - Scroll wheel up
  • 'WheelDown' - Scroll wheel down

​
Common Mouse Binding Examples

config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Left' } },
    mods = 'CTRL',
    action = wezterm.action.OpenLinkAtMouseCursor,
  },
}

​
Select Word on Double Click

config.mouse_bindings = {
  {
    event = { Down = { streak = 2, button = 'Left' } },
    mods = 'NONE',
    action = wezterm.action.SelectTextAtMouseCursor 'Word',
  },
}

​
Select Line on Triple Click

config.mouse_bindings = {
  {
    event = { Down = { streak = 3, button = 'Left' } },
    mods = 'NONE',
    action = wezterm.action.SelectTextAtMouseCursor 'Line',
  },
}

​
Paste on Middle Click

config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Middle' } },
    mods = 'NONE',
    action = wezterm.action.PasteFrom 'PrimarySelection',
  },
}

​
Custom Scrolling

config.mouse_bindings = {
  {
    event = { Down = { streak = 1, button = 'WheelUp' } },
    mods = 'CTRL',
    action = wezterm.action.IncreaseFontSize,
  },
  {
    event = { Down = { streak = 1, button = 'WheelDown' } },
    mods = 'CTRL',
    action = wezterm.action.DecreaseFontSize,
  },
}

​
Mouse Reporting

WezTerm supports SGR mouse reporting for applications like vim and tmux. This is enabled by default.

​
Disable Mouse Reporting for Specific Programs

config.bypass_mouse_reporting_modifiers = 'SHIFT'
Holding SHIFT will bypass mouse reporting and allow terminal-level mouse actions.

​
Disabling Default Mouse Bindings

To disable a default mouse binding: 
config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Left' } },
    mods = 'NONE',
    action = wezterm.action.DisableDefaultAssignment,
  },
}

​
Advanced Examples

​
Context Menu on Right Click

config.mouse_bindings = {
  {
    event = { Down = { streak = 1, button = 'Right' } },
    mods = 'NONE',
    action = wezterm.action_callback(function(window, pane)
      local clipboard = window:get_clipboard()
      window:toast_notification('WezTerm', clipboard, nil, 3000)
    end),
  },
}

​
Select with Alt+Click

config.mouse_bindings = {
  {
    event = { Down = { streak = 1, button = 'Left' } },
    mods = 'ALT',
    action = wezterm.action.SelectTextAtMouseCursor 'Cell',
  },
}

​
Drag to Create New Window

config.mouse_bindings = {
  {
    event = { Drag = { streak = 1, button = 'Left' } },
    mods = 'CTRL',
    action = wezterm.action.StartWindowDrag,
  },
}

​
Mouse Cursor Themes

Configure the mouse cursor appearance: 
-- On X11/Wayland
config.xcursor_theme = 'Adwaita'
config.xcursor_size = 24

​
See Also