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

> Configure tuicr mouse support to enable scroll wheel navigation, click-to-select, and drag-to-scroll by setting mouse = true in config.toml. Master terminal mouse events with ease.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-02

---

**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`:

```toml

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

mouse = true

```

The configuration parser in **[`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/main.rs) extracts the flag and passes it to the terminal builder:

```rust
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`](https://github.com/agavra/tuicr/blob/main/src/terminal_state.rs)**. When `mouse_enabled` is `true`, the code executes:

```rust
// 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`](https://github.com/agavra/tuicr/blob/main/src/main.rs)** forwards mouse events:

```rust
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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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:

```text
: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:

```rust
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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs)
- **Terminal activation** occurs through `TerminalState::mouse_enabled` and crossterm's `EnableMouseCapture` in [`src/terminal_state.rs`](https://github.com/agavra/tuicr/blob/main/src/terminal_state.rs)
- **Event dispatch** routes crossterm mouse events through `handle_mouse_event` in [`src/handler.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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.