How to Configure Mouse Support and Handle Terminal Mouse Events in tuicr

Enable mouse capture in tuicr by setting mouse = true in ~/.config/tuicr/config.toml, which activates scroll wheel navigation, click-to-select, and drag-to-scroll through crossterm's EnableMouseCapture primitive.

The tuicr terminal UI client supports comprehensive mouse interaction for users who prefer pointer-based navigation over keyboard shortcuts. This guide explains how to enable mouse support through configuration and how the event handling system processes clicks, scrolls, and drag gestures according to the agavra/tuicr source code.

Configuring Mouse Support in tuicr

Mouse support is opt-in and controlled through a single boolean flag in your configuration file.

Setting the Mouse Flag in config.toml

Add the following to your ~/.config/tuicr/config.toml:

# Enable mouse capture for scrolling, selection and drag-to-scroll

mouse = true

The configuration parser in src/config/mod.rs (lines 124-131) reads this as Option<bool>. When omitted, the default is None, which disables mouse capture entirely. Invalid types trigger a warning and are ignored, as verified by the test cases at lines 1189-1195.

Propagating the Configuration to the Terminal

After parsing, main.rs extracts the flag and passes it to the terminal builder:

let mouse_enabled = config_outcome
    .and_then(|cfg| cfg.mouse)      // src/main.rs, L267-L273
    .unwrap_or(false);
let terminal = TerminalState::new()
    .mouse_enabled(mouse_enabled)   // src/terminal_state.rs, L27-L28
    .build()?;

The TerminalState::mouse_enabled method stores this value for later activation when the backend initializes.

Activating Mouse Capture in the Terminal Backend

Actual mouse capture activation occurs during terminal initialization in src/terminal_state.rs. When mouse_enabled is true, the code executes:

// Enable mouse capture via crossterm (src/terminal_state.rs, L196)
EnableMouseCapture

The complementary deactivation helpers at lines 221-235 ensure clean shutdown by disabling mouse capture when tuicr exits, preventing your terminal from remaining in an altered state.

Handling Terminal Mouse Events

Once enabled, all mouse events flow through a dedicated handler that translates raw crossterm events into application actions.

Event Loop Dispatch

The main event loop in src/main.rs forwards mouse events:

Event::Mouse(mouse_event) => handle_mouse_event(&mut app, mouse_event),   // src/main.rs, L706

The Mouse Event Handler

The handle_mouse_event function in src/handler.rs (starting at line 155) processes three event categories:

• Scroll wheel — MouseEvent::Press(Button::ScrollUp, …) and ScrollDown update vertical scroll offsets or the commit-selector scroll position
• Button press and release — Left-button presses set app.mouse_drag_active = true; releases clear this flag
• Mouse movement — While mouse_drag_active is true, movement coordinates translate into click-and-drag scrolling of the diff view, with direction determined by delta values

The mouse_drag_active state field, defined in src/app/mod.rs at line 1072, persists across event loop iterations to track ongoing drag sessions.

Runtime Mouse Toggle Commands

For temporary control without editing configuration files, tuicr provides built-in commands:

:mouse on      # enable mouse capture for the current session

:mouse off     # disable mouse capture

These commands modify the same internal flag used during initialization, allowing on-the-fly switching based on your current task or terminal capabilities.

Programmatic Configuration (Library Usage)

When using tuicr as a library, enable mouse support through the builder pattern:

use tuicr::{App, Config};

let cfg = Config::builder().mouse(true).build()?;
let mut app = App::new_with_config(cfg)?;

This bypasses file-based configuration entirely while maintaining identical runtime behavior.

Edge Cases and Fallback Behavior

• Unsupported terminals: If EnableMouseCapture fails, deactivation helpers fall back gracefully without terminating the program
• Invalid configuration values: Non-boolean mouse values in config.toml are logged with warnings and treated as disabled
• Clean shutdown: Mouse capture state is always restored on exit, even during panic recovery

Summary

• Enable mouse support by adding mouse = true to ~/.config/tuicr/config.toml; parsed in src/config/mod.rs
• Terminal activation occurs through TerminalState::mouse_enabled and crossterm's EnableMouseCapture in src/terminal_state.rs
• Event dispatch routes crossterm mouse events through handle_mouse_event in src/handler.rs
• Gesture handling covers scroll wheels, button presses, and drag-to-scroll via the mouse_drag_active state in src/app/mod.rs
• Runtime control available through :mouse on and :mouse off commands

Frequently Asked Questions

Does tuicr require mouse support to function?

No. Mouse support is entirely optional. When disabled or unsupported by your terminal, tuicr operates fully through keyboard navigation without degraded functionality.

What happens if my terminal does not support mouse events?

The EnableMouseCapture call in src/terminal_state.rs will fail silently during initialization, and tuicr will continue in keyboard-only mode. The deactivation helpers at lines 221-235 ensure no error propagates to the user.

Can I enable mouse support for only specific views or modes?

The current implementation enables mouse capture globally for the entire application session. There is no per-view granularity; however, individual handlers can choose to ignore mouse events based on application state.

How does drag scrolling work in the diff view?

When you press and hold the left mouse button, handle_mouse_event sets mouse_drag_active = true in the application state. Subsequent mouse movement events calculate coordinate deltas and apply them as scroll offsets to the diff view until button release clears the flag.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}