claude-code/packages/@ant/ink/docs/09-hooks-reference.md

Chapter 9: Hooks Reference

Complete API reference for all hooks exported by @anthropic/ink.

---

Application Hooks

useApp()

Access app-level operations.

function useApp(): {
  exit: (error?: Error) => void
}

Example:

const { exit } = useApp()
// Gracefully unmount and exit
exit()

useStdin()

Access the stdin stream and raw mode control.

function useStdin(): {
  stdin: NodeJS.ReadStream
  isRawModeSupported: boolean
  setRawMode: (enabled: boolean) => void
  internal_exitOnCtrlC: boolean
  internal_eventEmitter: EventEmitter | undefined
  internal_querier: TerminalQuerier | null
}

Prefer useInput for keyboard handling.

---

Input Hooks

useInput(handler, options?)

Handle keyboard input. See Chapter 7 for full details.

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

---

Terminal Hooks

useTerminalSize()

Get current terminal dimensions.

function useTerminalSize(): {
  columns: number
  rows: number
}

Throws if used outside <App>.

useTerminalFocus()

Track whether the terminal window is focused.

function useTerminalFocus(): boolean

Uses DECSET 1004 focus reporting. Returns true when focused.

useTerminalTitle(title)

Set the terminal window title.

function useTerminalTitle(title: string | null): void

Pass null to clear the title.

useTerminalViewport()

Track element visibility in the terminal viewport.

function useTerminalViewport(): [
  ref: (element: DOMElement | null) => void,
  entry: { isVisible: boolean }
]

Example:

const [viewportRef, { isVisible }] = useTerminalViewport()

<Box ref={viewportRef}>
  <Text>{isVisible ? 'Visible' : 'Scrolled off'}</Text>
</Box>

useTabStatus(kind)

Set tab status indicator in terminal tab bar (OSC 21337).

type TabStatusKind = 'idle' | 'busy' | 'waiting'
function useTabStatus(kind: TabStatusKind | null): void

useTerminalNotification()

Send terminal notifications (iTerm2, Kitty, Ghostty, bell).

function useTerminalNotification(): {
  notifyITerm2: (opts: { message: string; title?: string }) => void
  notifyKitty: (opts: { message: string; title: string; id: number }) => void
  notifyGhostty: (opts: { message: string; title: string }) => void
  notifyBell: () => void
  progress: (state: Progress['state'] | null, percentage?: number) => void
}

Requires TerminalWriteProvider in the tree.

Progress states: 'running', 'completed', 'error', 'indeterminate', null (clear).

---

Animation & Timing Hooks

useInterval(callback, intervalMs)

Clock-backed interval timer.

function useInterval(callback: () => void, intervalMs: number | null): void

Pass null to pause. Shares the application clock for efficient batching.

useAnimationTimer(intervalMs)

Returns the current clock time, updating at the given interval.

function useAnimationTimer(intervalMs: number): number

Subscribes as non-keepAlive -- won't keep the clock running on its own.

useAnimationFrame(intervalMs?)

Synchronized animation hook that pauses when offscreen.

function useAnimationFrame(
  intervalMs?: number | null,  // default 16
): [ref: (element: DOMElement | null) => void, time: number]

Returns a ref callback (attach to animated element) and the current animation time. All instances share the same clock. Pass null to pause.

const [ref, time] = useAnimationFrame(120)
const frame = Math.floor(time / 120) % FRAMES.length
return <Box ref={ref}>{FRAMES[frame]}</Box>

useTimeout(delayMs, resetTrigger?)

One-shot timer.

function useTimeout(delay: number, resetTrigger?: number): boolean

Returns true when the timeout has elapsed. Change resetTrigger to restart.

useMinDisplayTime(value, minMs)

Ensure a value is displayed for at least minMs milliseconds.

function useMinDisplayTime<T>(value: T, minMs: number): T

Holds the previous value until minMs has elapsed, then switches to the new value.

Example:

// Keep showing "Loading" for at least 300ms to prevent flash
const displayValue = useMinDisplayTime(isLoading ? 'loading' : 'done', 300)

---

Interaction Hooks

useDoublePress(setPending, onDoublePress, onFirstPress?)

Detect double-press (double-click equivalent for keyboard).

export const DOUBLE_PRESS_TIMEOUT_MS = 800

function useDoublePress(
  setPending: (pending: boolean) => void,
  onDoublePress: () => void,
  onFirstPress?: () => void
): () => void  // Returns the press handler

Example:

const [pendingExit, setPendingExit] = useState(false)
const handlePress = useDoublePress(
  setPendingExit,
  () => exit(),       // Double press
  () => {},           // First press
)

useInput((input, key) => {
  if (key.escape) handlePress()
})

useExitOnCtrlCD(options?)

Handle Ctrl+C / Ctrl+D with double-press confirmation.

type ExitState = {
  pending: boolean
  keyName: 'Ctrl-C' | 'Ctrl-D' | null
}

function useExitOnCtrlCDWithKeybindings(
  onExit?: () => void,
  onInterrupt?: () => boolean,
  isActive?: boolean
): ExitState

Example:

const exitState = useExitOnCtrlCDWithKeybindings(
  () => exit(),
  () => { /* return true to prevent exit */ }
)

if (exitState.pending) {
  return <Text>Press {exitState.keyName} again to exit</Text>
}

---

Selection Hooks (Alt-Screen Only)

useSelection()

Text selection operations.

function useSelection(): {
  copySelection: () => string
  copySelectionNoClear: () => string
  clearSelection: () => void
  hasSelection: () => boolean
  getState: () => SelectionState | null
  subscribe: (cb: () => void) => () => void
  shiftAnchor: (dRow: number, minRow: number, maxRow: number) => void
  shiftSelection: (dRow: number, minRow: number, maxRow: number) => void
  moveFocus: (move: FocusMove) => void
  captureScrolledRows: (firstRow: number, lastRow: number, side: 'above' | 'below') => void
  setSelectionBgColor: (color: string) => void
}

useHasSelection()

Reactive boolean for selection state.

function useHasSelection(): boolean

Re-renders when selection is created or cleared.

---

Search Hooks

useSearchHighlight()

Set and manage search highlighting.

function useSearchHighlight(): {
  setQuery: (query: string) => void
  scanElement: (el: DOMElement) => MatchPosition[]
  setPositions: (state: { positions: MatchPosition[]; rowOffset: number; currentIdx: number } | null) => void
}

useSearchInput(options)

Search input handler with cursor management.

type UseSearchInputOptions = {
  isActive: boolean
  onExit: () => void
  onCancel?: () => void
  onExitUp?: () => void
  columns?: number
  passthroughCtrlKeys?: string[]
  initialQuery?: string
  backspaceExitsOnEmpty?: boolean
}

type UseSearchInputReturn = {
  query: string
  setQuery: (q: string) => void
  cursorOffset: number
  handleKeyDown: (e: KeyboardEvent) => void
}

function useSearchInput(options: UseSearchInputOptions): UseSearchInputReturn

---

Cursor Hooks

useDeclaredCursor(options)

Park the terminal cursor at a specific position for IME and accessibility.

function useDeclaredCursor({
  line: number,
  column: number,
  active: boolean
}): (element: DOMElement | null) => void

Returns a ref callback. Position is relative to the ref'd element.

Example:

const cursorRef = useDeclaredCursor({
  line: 0,
  column: cursorPosition,
  active: isFocused,
})

return <Box ref={cursorRef}>...</Box>

---

Tab Status Hooks

useTabStatus(kind)

Set tab status indicator (OSC 21337) for terminal tab bars.

type TabStatusKind = 'idle' | 'busy' | 'waiting'

function useTabStatus(kind: TabStatusKind | null): void

Pass null to clear.

---

Viewport Hooks

useTerminalViewport()

Track element visibility within the terminal viewport.

function useTerminalViewport(): [
  ref: (element: DOMElement | null) => void,
  entry: { isVisible: boolean }
]

Returns a ref callback and visibility state.