claude-code/packages/@ant/ink/docs/07-user-input.md

Chapter 7: User Input

useInput

The primary hook for handling keyboard input.

import { useInput } from '@anthropic/ink'

function MyComponent() {
  useInput((input, key, event) => {
    if (input === 'q') {
      // 'q' key pressed
    }
    if (key.leftArrow) {
      // Left arrow
    }
    if (key.ctrl && input === 'c') {
      // Ctrl+C (only if exitOnCtrlC is false)
    }
    if (key.meta && input === 'b') {
      // Alt+B (Option+B on Mac)
    }
    if (key.shift && input === 'Tab') {
      // Shift+Tab
    }
  })

  return <Text>Press keys...</Text>
}

Signature

function useInput(
  handler: (input: string, key: Key, event: InputEvent) => void,
  options?: { isActive?: boolean }
): void

Parameters

• input (string) -- The character entered. Empty string for non-printable keys (arrows, function keys). For paste events, the entire pasted text.
• key (Key) -- Parsed key metadata (see below)
• event (InputEvent) -- Raw event with stopImmediatePropagation()

Options

Option	Type	Default	Description
isActive	boolean	true	Enable/disable input handling

Key Object

type Key = {
  upArrow: boolean
  downArrow: boolean
  leftArrow: boolean
  rightArrow: boolean
  pageDown: boolean
  pageUp: boolean
  wheelUp: boolean       // Mouse wheel in alt-screen
  wheelDown: boolean      // Mouse wheel in alt-screen
  home: boolean
  end: boolean
  return: boolean
  escape: boolean
  ctrl: boolean
  shift: boolean
  fn: boolean
  tab: boolean
  backspace: boolean
  delete: boolean
  meta: boolean           // Alt / Option
  super: boolean          // Cmd (macOS) / Win key
}

Event Propagation

Multiple useInput handlers form a chain. Call event.stopImmediatePropagation() to prevent downstream handlers from receiving the event:

useInput((input, key, event) => {
  if (input === 'j') {
    // Consumed by this handler
    event.stopImmediatePropagation()
  }
  // Other handlers won't see 'j'
})

useInput((input, key) => {
  // This won't fire for 'j'
})

Raw Mode

useInput automatically enables raw mode on stdin when active. Raw mode is reference-counted -- it stays enabled as long as any hook has isActive: true.

In raw mode:

• Keystrokes don't echo
• Ctrl+C is not sent as signal (app must handle it)
• Line buffering is disabled

InputEvent

class InputEvent extends Event {
  readonly input: string
  readonly key: Key
  readonly keypress: ParsedKey  // Raw parsed keypress data
}

KeyboardEvent

DOM-like keyboard event dispatched to focused elements:

class KeyboardEvent extends Event {
  readonly key: Key
}

Used with Box's onKeyDown and onKeyDownCapture props:

<Box
  tabIndex={0}
  autoFocus
  onKeyDown={(event) => {
    if (event.key.return) {
      handleSubmit()
    }
  }}
>
  <Text>Press Enter to submit</Text>
</Box>

Key Parsing

Ink supports multiple keyboard protocols:

Standard Escape Sequences

• Arrow keys, function keys, Home/End, Page Up/Down
• Ctrl+letter combinations
• Shift, Alt, Meta modifiers

Kitty Keyboard Protocol (CSI u)

Extended key reporting with full modifier support:

• Distinguishes Ctrl+Shift+A from Ctrl+A
• Reports Super (Cmd/Win) key
• Sends key release events

xterm modifyOtherKeys

Alternative extended key reporting for xterm-compatible terminals.

Application Keypad Mode

Numpad keys mapped to their digit characters.

Paste Detection

When Bracketed Paste mode is enabled (DECSET 2004), pasted text is delivered as a single InputEvent with the full text in input. This distinguishes paste from rapid typing:

useInput((input, key, event) => {
  if (event.keypress.paste) {
    // User pasted text -- handle as a batch
    handlePaste(input)
  } else {
    // Regular keypress
    handleKey(input, key)
  }
})

Mouse Events (Alt-Screen Only)

In alternate screen mode, mouse events are parsed and dispatched:

Click Events

<Box
  onClick={(event) => {
    console.log(`Clicked at (${event.x}, ${event.y})`)
    event.stopImmediatePropagation()
  }}
>
  <Text>Click me</Text>
</Box>

Hover Events

<Box
  onMouseEnter={() => setHovered(true)}
  onMouseLeave={() => setHovered(false)}
>
  <Text>{hovered ? 'Hovered!' : 'Hover me'}</Text>
</Box>

Hover events use mouseenter/mouseleave semantics (no bubbling between children).

Wheel Events

Mouse wheel events arrive as Key.wheelUp/Key.wheelDown:

useInput((input, key) => {
  if (key.wheelUp) scrollUp()
  if (key.wheelDown) scrollDown()
})

useStdin

Lower-level access to the stdin stream.

import { useStdin } from '@anthropic/ink'

const {
  stdin,                    // Raw stdin stream
  setRawMode,               // (enabled: boolean) => void
  isRawModeSupported,       // boolean
  internal_exitOnCtrlC,     // boolean
  internal_eventEmitter,    // EventEmitter | undefined
  internal_querier,         // Terminal querier
} = useStdin()

Prefer useInput for keyboard handling. useStdin is for advanced use cases like terminal querying or custom event handling.

Button Component

Interactive button that responds to keyboard and mouse:

import { Button } from '@anthropic/ink'

<Button onAction={() => handleClick()} tabIndex={0} autoFocus>
  {(state) => (
    <Text bold={state.focused} color={state.focused ? 'claude' : 'text'}>
      {state.focused ? '> Click Me' : '  Click Me'}
    </Text>
  )}
</Button>

Button receives a render prop with state:

type ButtonState = {
  focused: boolean    // Has keyboard focus
  hovered: boolean    // Mouse is over it (alt-screen)
  active: boolean     // True for 100ms after activation (flash effect)
}

Activation triggers: Enter key, Space key, or mouse click.