Mouse Support

Mouse support in TUIs is optional but enhances usability. This guide covers mouse event handling.

Mouse events

Not all terminals support mouse events. When available, Nocterm handles mouse clicks, scrolling, and movement.

Automatic mouse support

Some components handle mouse automatically:

• ListView: Mouse wheel scrolling
• TextField: Click to position cursor
• Buttons and interactive components

Terminal compatibility

Mouse support varies:

• Works: iTerm2, Windows Terminal, modern terminals
• Limited: macOS Terminal (basic support)
• None: Some older or minimal terminals

Always provide keyboard alternatives for accessibility.

Best practices

Always provide keyboard alternatives

Every mouse action needs a keyboard shortcut:

Column(
  children: [
    // Works with both mouse and keyboard
    Button(
      onPressed: () => save(),
      child: Text('Save (Ctrl+S)'),
    ),
  ],
)

Test without mouse

Ensure your app works without a mouse:

1. Disable mouse in your terminal settings
2. Navigate your entire app using only keyboard
3. Check that all features remain accessible

Use mouse for convenience

Mouse is a convenience feature, not a requirement:

• Quick selection in lists
• Faster scrolling
• Point-and-click for discovery

But keyboard should always be sufficient.

Document mouse features

Tell users about mouse support:

Text('Use arrow keys or mouse wheel to scroll')

When to use mouse

Mouse works well for:

• Scrolling long lists
• Clicking buttons
• Selecting items from menus
• Positioning cursor in text

Mouse is less useful for:

• Complex navigation
• Rapid input
• Automation
• Accessibility

Terminal-specific behavior

Different terminals handle mouse differently:

iTerm2 (macOS):

• Full mouse support
• Clicks, scrolling, hover
• Best mouse experience

Windows Terminal:

• Good mouse support
• Clicks and scrolling work well

macOS Terminal:

• Basic mouse support
• Some features may not work

tmux/screen:

• Mouse pass-through may need configuration
• Test in your target environment

Next steps

• Focus Management - Manage keyboard focus
• Keyboard Events - Handle keyboard input
• Input - Input components