wezterm/docs/config/mouse.md

Mouse bindings are configurable, and there are a number of default assignments described below.

The assignments are based around a triggering mouse event which may be combined with a set of modifier keys to produce an action.

By default applications running in the terminal don't respond to the mouse. However, applications can emit escape sequences to request mouse event tracking. When mouse event tracking is enabled, mouse events are NOT matched against the mouse assignments and are instead passed through to the application.

You can bypass the mouse reporting capture by holding down the SHIFT key; that will prevent the event from being passed to the application and allow matching it against your assignments as though the SHIFT key were not pressed.

The bypass_mouse_reporting_modifiers option allows you to specify an alternative set of modifiers to use for bypassing mouse reporting capture.

Default Mouse Assignments

In the table below, Triple Left Down means that the left mouse button is being triple clicked and that the event matches the downstroke of the third quick consecutive press. Triple Left Up matches the subsequent release event of that triple click, so for a triple click both SelectTextAtMouseCursor="Line" and CompleteSelection will be triggered in that order.

NOTE: In the action column, act is an alias to wezterm.action (to avoid repetition).

Event	Modifiers	Action
Triple Left Down	NONE	act.SelectTextAtMouseCursor("Line")
Double Left Down	NONE	act.SelectTextAtMouseCursor("Word")
Single Left Down	NONE	act.SelectTextAtMouseCursor("Cell")
Single Left Down	SHIFT	act.ExtendSelectionToMouseCursor("Cell")
Single Left Down	ALT	act.SelectTextAtMouseCursor("Block") (since: 20220624-141144-bd1b7c5d)
Single Left Up	SHIFT	act.CompleteSelectionOrOpenLinkAtMouseCursor("PrimarySelection")
Single Left Up	NONE	act.CompleteSelectionOrOpenLinkAtMouseCursor("PrimarySelection")
Single Left Up	ALT	act.CompleteSelection("PrimarySelection") (since: 20220624-141144-bd1b7c5d)
Double Left Up	NONE	act.CompleteSelection("PrimarySelection")
Triple Left Up	NONE	act.CompleteSelection("PrimarySelection")
Single Left Drag	NONE	act.ExtendSelectionToMouseCursor("Cell")
Single Left Drag	ALT	act.ExtendSelectionToMouseCursor("Block") (since: 20220624-141144-bd1b7c5d)
Single Left Down	ALT+SHIFT	act.ExtendSelectionToMouseCursor("Block") (since: 20220624-141144-bd1b7c5d)
Single Left Up	ALT+SHIFT	act.CompleteSelection("PrimarySelection") (since: 20220624-141144-bd1b7c5d)
Double Left Drag	NONE	act.ExtendSelectionToMouseCursor("Word")
Triple Left Drag	NONE	act.ExtendSelectionToMouseCursor("Line")
Single Middle Down	NONE	act.PasteFrom("PrimarySelection")
Single Left Drag	SUPER	act.StartWindowDrag (since 20210314-114017-04b7cedd)
Single Left Drag	CTRL+SHIFT	act.StartWindowDrag (since 20210314-114017-04b7cedd)

If you don't want the default assignments to be registered, you can disable all of them with this configuration; if you chose to do this, you must explicitly register every binding.

return {
  disable_default_mouse_bindings = true,
}

Configuring Mouse Assignments

since: 20200607-144723-74889cd4

You can define mouse actions using the mouse_bindings configuration section:

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  mouse_bindings = {
    -- Right click sends "woot" to the terminal
    {
      event = { Down = { streak = 1, button = 'Right' } },
      mods = 'NONE',
      action = act.SendString 'woot',
    },

    -- Change the default click behavior so that it only selects
    -- text and doesn't open hyperlinks
    {
      event = { Up = { streak = 1, button = 'Left' } },
      mods = 'NONE',
      action = act.CompleteSelection 'PrimarySelection',
    },

    -- and make CTRL-Click open hyperlinks
    {
      event = { Up = { streak = 1, button = 'Left' } },
      mods = 'CTRL',
      action = act.OpenLinkAtMouseCursor,
    },
    -- NOTE that binding only the 'Up' event can give unexpected behaviors.
    -- Read more below on the gotcha of binding an 'Up' event only.
  },
}

The action and mods portions are described in more detail in the key assignment information below.

The event portion has three components:

• Whether it is a Down, Up or Drag event
• The number of consecutive clicks within the click threshold (the click streak)
• The mouse button; Left, Right, or Middle.

A double click is a down-up-down sequence where either the second button down is held for long enough or is released and no subsequent down event occurs within the click threshold. When recognized, it emits a Down event with streak=2. If the mouse is moved while the button is held, a Drag event with streak=2 is generated. When the mouse button is released an Up event with streak=2 is generated.

The mouse event recognizer supports an arbitrary click streak, so if you wanted quadruple-click bindings you can specify streak=4.

Event	Lua Representation
Triple Left Down	event={Down={streak=3, button="Left"}}
Double Left Up	event={Up={streak=2, button="Left"}}
Single Left Drag	event={Drag={streak=1, button="Left"}}

since: nightly builds only

You can handle scroll events by using 'WheelUp' or 'WheelDown' as event. Currently, this only works with at least one modifier being present.

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  mouse_bindings = {
    -- Scrolling up while holding CTRL increases the font size
    {
      event = 'WheelUp',
      mods = 'CTRL',
      action = act.IncreaseFontSize,
    },

    -- Scrolling down while holding CTRL decreases the font size
    {
      event = 'WheelDown',
      mods = 'CTRL',
      action = act.DecreaseFontSize,
    },
  },
}

Take a look at window:current_event, if you want to access the delta scroll value while handling the event.

Gotcha on binding an 'Up' event only

If you only have a mouse bind on the 'Up' event and not on the 'Down' event, the 'Down' event will still be sent to the running program. If that program is tracking mouse inputs (like tmux or vim with mouse support), you may experience unintuitive behavior as the program receives the 'Down' event, but not the 'Up' event (which is bound to something in your config).

To avoid this, it is recommended to disable the 'Down' event (to ensure it won't be sent to the running program), for example:

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  mouse_bindings = {
    -- Bind 'Up' event of CTRL-Click to open hyperlinks
    {
      event = { Up = { streak = 1, button = 'Left' } },
      mods = 'CTRL',
      action = act.OpenLinkAtMouseCursor,
    },
    -- Disable the 'Down' event of CTRL-Click to avoid weird program behaviors
    {
      event = { Down = { streak = 1, button = 'Left' } },
      mods = 'CTRL',
      action = act.Nop,
    },
  },
}

Available Actions

See the KeyAssignment reference for information on available actions.