# Mouse Features
par-term provides comprehensive mouse support for text selection, URL handling, and pane management.
## Table of Contents
- [Overview](#overview)
- [Text Selection](#text-selection)
- [URL Handling](#url-handling)
- [Semantic History](#semantic-history)
- [Cursor Positioning](#cursor-positioning)
- [Scrolling](#scrolling)
- [Pane Interaction](#pane-interaction)
- [Configuration](#configuration)
- [Platform Differences](#platform-differences)
- [Known Fixes](#known-fixes)
- [Related Documentation](#related-documentation)
## Overview
Mouse interactions in par-term:
```mermaid
graph TD
Mouse[Mouse Input]
Left[Left Button]
Middle[Middle Button]
Right[Right Button]
Wheel[Scroll Wheel]
Mouse --> Left
Mouse --> Middle
Mouse --> Right
Mouse --> Wheel
Left --> Selection[Text Selection]
Left --> URLs[URL Clicking]
Left --> Files[File Path Opening]
Left --> Cursor[Cursor Position]
Left --> Scrollbar[Scrollbar]
Left --> Divider[Pane Dividers]
Middle --> Paste[Paste Primary]
Right --> AppMouse[App Mouse Tracking]
Wheel --> Scroll[Scrolling]
style Mouse fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
style Left fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
style Middle fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
style Right fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
style Wheel fill:#880e4f,stroke:#c2185b,stroke-width:2px,color:#ffffff
style Selection fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style URLs fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style Files fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style Cursor fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style Scrollbar fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style Divider fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style Paste fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style AppMouse fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style Scroll fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
```
## Text Selection
### Selection Modes
| Click + Drag | Normal | Character-by-character selection |
| Double-Click | Word | Select word at cursor |
| Triple-Click | Line | Select entire line |
| Alt+Cmd/Super + Drag | Rectangular | Column-based block selection (Option+Cmd on macOS, Alt+Win on Windows/Linux) |
### Word Selection
Double-click selects a word based on word boundary characters.
**Default word characters:** `/-+\~_.` (alphanumeric + these)
Configure in `config.yaml`:
```yaml
word_characters: "/-+\\~_."
```
### Smart Selection
When enabled, double-click can detect and select:
- URLs (http://, https://, etc.)
- Email addresses
- File paths
- IP addresses
Configure:
```yaml
smart_selection_enabled: true
```
### Auto-Copy
Selected text is automatically copied to clipboard when selection ends:
```yaml
auto_copy_selection: true
copy_trailing_newline: false # Strip trailing newlines
```
### Click Timing
Configure double/triple-click detection:
```yaml
mouse_double_click_threshold: 500 # milliseconds (default)
mouse_triple_click_threshold: 500 # milliseconds (default)
```
## URL Handling
### Opening URLs
Hold `Cmd` (macOS) or `Ctrl` (Windows/Linux) and click a URL to open it.
**Detected Schemes:**
- `http://`, `https://`
- `ftp://`, `ftps://`
- `file://`, `git://`, `ssh://`
- `www.*` (converted to https://)
**Visual Feedback:**
- Cursor changes to hand pointer on URL hover
- Window title shows URL as tooltip
### OSC 8 Hyperlinks
par-term supports terminal-embedded hyperlinks (OSC 8 protocol) for more reliable URL detection.
## Semantic History
### Opening File Paths
Hold `Cmd` (macOS) or `Ctrl` (Windows/Linux) and click a detected file path to open it in your editor.
**Detected Paths:**
- Absolute paths: `/Users/name/projects/main.rs`, `/etc/config.yaml`
- Relative paths: `./src/main.rs`, `../lib/utils.py`
- Home-relative paths: `~/projects/app.js`
- Paths with line numbers: `./src/main.rs:42` or `./src/main.rs:42:10`
**Visual Feedback:**
- Detected paths are highlighted with a configurable color (default: bright cyan) and optional underline
- Underline style (solid or stipple) and visibility are configurable
- Cursor changes to hand pointer on hover
**Editor Selection:**
- Uses `$EDITOR` / `$VISUAL` by default
- Configurable custom editor command with `{file}`, `{line}`, `{col}` placeholders
- Directories open in the system file manager
Configure:
```yaml
semantic_history_enabled: true
semantic_history_editor_mode: environment_variable # or: custom, system_default
semantic_history_editor: "code -g {file}:{line}" # custom mode only
```
> See [Semantic History](SEMANTIC_HISTORY.md) for full documentation.
## Cursor Positioning
### Option/Alt + Click
Move the text cursor to the clicked position:
| macOS | `Option + Click` |
| Windows/Linux | `Alt + Click` |
**Requirements:**
- Must be at bottom of scrollback (not scrolled up)
- Not on alternate screen (apps like vim handle their own cursor)
- Not combined with Cmd/Super
Configure:
```yaml
option_click_moves_cursor: true
```
## Scrolling
### Mouse Wheel
Scroll through the scrollback buffer with the mouse wheel.
Configure scroll speed:
```yaml
mouse_scroll_speed: 3.0 # Lines per scroll tick (default)
```
### Scrollbar
- **Click thumb:** Drag to scroll
- **Click track:** Jump to position
- **Drag:** Smooth scrolling
### Application Scrolling
When a terminal application requests mouse tracking (vim, htop, etc.), scroll events are forwarded to the application instead of scrolling locally.
### Right-Click
Right-click forwards the event to the terminal application when mouse tracking is enabled. This allows applications like tmux and vim to handle right-click for their own context menus or actions.
## Pane Interaction
### Focus Panes
Click on a pane to focus it.
### Resize Panes
Drag the divider between panes to resize:
- Horizontal dividers: resize height
- Vertical dividers: resize width
**Visual Feedback:**
- Cursor changes to resize indicator on divider hover
- Dividers sync to tmux if gateway is active
## Configuration
### All Mouse Options
```yaml
# Selection behavior
auto_copy_selection: true
copy_trailing_newline: false
word_characters: "/-+\\~_."
smart_selection_enabled: true
# Click timing
mouse_double_click_threshold: 500
mouse_triple_click_threshold: 500
# Scroll behavior
mouse_scroll_speed: 3.0
report_horizontal_scroll: true
# Cursor movement
option_click_moves_cursor: true
# Paste behavior
middle_click_paste: true
# Window focus
focus_follows_mouse: false
```
### Settings UI
The Input tab in Settings provides:
| **Auto-copy selection** | Copy to clipboard on selection |
| **Copy trailing newline** | Include newlines when copying |
| **Middle-click paste** | Enable middle-click paste |
| **Option-click moves cursor** | Alt/Option+click cursor positioning |
| **Focus follows mouse** | Auto-focus window on cursor enter |
## Platform Differences
| URL modifier | `Cmd` | `Ctrl` |
| Cursor move | `Option` | `Alt` |
| Rectangular select | `Option + Cmd` | `Alt + Win` |
| Primary selection | No | Yes (X11) |
| Middle-click paste | Clipboard | Primary selection |
## Known Fixes
The following mouse-related issues have been resolved:
- **Text Selection in Mouse-Tracking Apps** -- Holding Shift while clicking or dragging now bypasses application mouse tracking to allow local text selection. This matches the standard behavior of iTerm2, Kitty, and Alacritty for apps like `less`, `vim`, and `htop` that enable mouse tracking on the alternate screen
- **Trackpad Jitter Selection** -- Increased the mouse drag dead-zone threshold from 4 px to 8 px so that trackpad tap-to-click movement noise and minor jitter no longer create unintended micro-selections that overwrite clipboard content
- **tmux Pane Click Through Clipboard Guard** -- Clicking to switch tmux panes no longer fails when an image is in the clipboard. The clipboard-image protection guard now correctly allows mouse-tracked clicks to pass through to the terminal application
- **Clipboard Image Loss on Plain Click** -- When an image was present in the system clipboard, a single left-click inside an already-focused terminal window with mouse reporting (e.g., tmux) could clear the image from the clipboard. par-term now snapshots the clipboard image on mouse-down and restores it after a plain click-like gesture (no drag, no modifier keys) if the image was lost during the click
- **Middle-Click Paste Priority** -- Middle-click paste now takes priority over mouse tracking and alternate screen mode, matching iTerm2 behavior. This ensures paste works reliably even in applications like tmux that enable mouse tracking
- **Middle-Click Paste Focuses tmux Pane** -- When middle-clicking in tmux mode with mouse tracking active, par-term now sends a synthetic left-click press/release at the cursor position before pasting, matching iTerm2 behaviour. This ensures the correct tmux pane is focused before the paste arrives
- **tmux Selection Stuck Across Panes** -- When a mouse press is consumed by mouse tracking (e.g., clicking a tmux pane), the local selection state is now cleared immediately. Previously, a stale highlight could persist across all panes indefinitely until the next local mouse interaction
- **Stale Mouse State on Pane Focus Switch** -- Clicking to switch focus between split panes could leave `button_pressed = true` on the old pane, causing spurious text selection on the next click back. The old pane's mouse state is now explicitly cleared during focus transfer
## Related Documentation
- [README.md](../README.md) - Project overview
- [Keyboard Shortcuts](KEYBOARD_SHORTCUTS.md) - Keyboard shortcut reference
- [Semantic History](SEMANTIC_HISTORY.md) - File path clicking details