> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# Mouse Bindings

> Configure mouse button actions and gestures in WezTerm

## 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

```lua theme={null}
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:

<ParamField path="event" type="object" required>
  The mouse event to bind.
</ParamField>

<ParamField path="mods" type="string">
  Optional modifier keys (CTRL, SHIFT, ALT, SUPER).
</ParamField>

<ParamField path="action" type="KeyAssignment" required>
  The action to perform.
</ParamField>

### Event Types

**Down** - Mouse button pressed:

```lua theme={null}
event = { Down = { streak = 1, button = 'Left' } }
```

**Up** - Mouse button released:

```lua theme={null}
event = { Up = { streak = 1, button = 'Left' } }
```

**Drag** - Mouse moved while button held:

```lua theme={null}
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

### Open Links with Ctrl+Click

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

### Select Word on Double Click

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

### Select Line on Triple Click

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

### Paste on Middle Click

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

### Custom Scrolling

```lua theme={null}
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

```lua theme={null}
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:

```lua theme={null}
config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Left' } },
    mods = 'NONE',
    action = wezterm.action.DisableDefaultAssignment,
  },
}
```

## Advanced Examples

### Context Menu on Right Click

```lua theme={null}
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

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

### Drag to Create New Window

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

## Mouse Cursor Themes

Configure the mouse cursor appearance:

```lua theme={null}
-- On X11/Wayland
config.xcursor_theme = 'Adwaita'
config.xcursor_size = 24
```

## See Also

* [Key Bindings](/config/keys)
* [Mouse Actions](/lua/keyassignment/copy-paste)
* [Selection Actions](/lua/keyassignment/overview)