ink-use-mouse

The mouse support Ink never built.

Click, hover, scroll, and drag in your terminal UI. Works with Ink 4+.

Install

npm install ink-use-mouse

Quick start

import { useMouse } from 'ink-use-mouse';

function App() {
  const mouse = useMouse();
  return <Text>Mouse at ({mouse.x}, {mouse.y}) {mouse.isPressed ? 'CLICK' : ''}</Text>;
}

API

useMouse() — raw mouse events

Returns the latest mouse state, updated on every move, click, and scroll.

const mouse = useMouse();
// mouse.x        — column (0-based)
// mouse.y        — row (0-based)
// mouse.button   — 'left' | 'middle' | 'right' | 'none'
// mouse.type     — 'press' | 'release' | 'move' | 'scroll-up' | 'scroll-down'
// mouse.isPressed — true if a button is held
// mouse.isActive  — true if mouse tracking is enabled

useMouseZone(ref) — hit testing

Detects if mouse events land inside a component's bounds.

function Button({ label, onPress }) {
  const ref = useRef(null);
  const { isHovered, isClicked } = useMouseZone(ref, { onClick: onPress });
  return (
    <Box ref={ref}>
      <Text color={isHovered ? '#F5D76E' : 'white'}>{label}</Text>
    </Box>
  );
}

<Clickable> — high-level click handler

<Clickable onClick={() => doSomething()}>
  <Text>Click me</Text>
</Clickable>

<Hoverable> — hover-aware rendering

<Hoverable>
  {(hovered) => <Text color={hovered ? 'yellow' : 'white'}>Item</Text>}
</Hoverable>

Terminal compatibility

| Terminal | Status | |----------|--------| | iTerm2 | Full support | | macOS Terminal | Full support | | Ghostty | Full support | | VS Code terminal | Full support | | tmux | Requires set -g mouse on in .tmux.conf | | Windows Terminal | Full support | | Alacritty | Full support |

SGR extended mode (\x1b[?1006h) is supported by all modern terminals. Legacy X10/Normal mode terminals (rare) are not supported.

How it works

1. On mount, enables SGR mouse reporting via \x1b[?1003h\x1b[?1006h
2. Parses stdin for SGR mouse escape sequences (\x1b[<Cb;Cx;CyM)
3. On unmount, disables reporting via \x1b[?1003l\x1b[?1006l

The parser handles all SGR events: press, release, motion, scroll, and button identification.

Low-level parser

If you need to parse mouse events outside of React:

import { parseMouseEvents } from 'ink-use-mouse';

const events = parseMouseEvents(rawStdinData);
// [{ x: 10, y: 5, button: 'left', type: 'press', isPressed: true }]

Part of the Exe ecosystem

Built for the Exe OS terminal UI. Works standalone with any Ink app.

License

MIT