giggles

Input

API reference for the input system

The input system routes keyboard events to focused components and prevents input leaking.

Basic Usage
import { useKeybindings, useFocus } from 'giggles';
import { useState } from 'react';
import { Box, Text } from 'ink';

function FileList() {
  const focus = useFocus();
  const [selected, setSelected] = useState(0);
  const files = ['file1.ts', 'file2.ts', 'file3.ts'];

  useKeybindings(focus, {
    j: () => setSelected((i) => Math.min(files.length - 1, i + 1)),
    k: () => setSelected((i) => Math.max(0, i - 1)),
  });

  return (
    <Box flexDirection="column">
      {files.map((file, i) => (
        <Text key={file} color={i === selected ? 'green' : 'white'}>
          {i === selected ? '> ' : '  '}
          {file}
        </Text>
      ))}
    </Box>
  );
}

API Reference

useKeybindings()

Registers keybindings that only fire when the component is focused.

Type Signature
function useKeybindings(
  focus: { id: string },
  bindings: Keybindings,
  options?: KeybindingOptions
): void

Parameters:

Prop

Type

KeyHandler

Handler function for a key binding.

Type Signature
type KeyHandler = (input: string, key: Key) => void

Prop

Type

Keybindings

Prop

Type

KeybindingOptions

Prop

Type

FocusTrap

Stops input bubbling at a boundary. Used for modals and dialogs.

FocusTrap Example
function App() {
  const [showModal, setShowModal] = useState(false);

  return (
    <>
      <MainContent />
      {showModal && (
        <FocusTrap>
          <Modal onClose={() => setShowModal(false)} />
        </FocusTrap>
      )}
    </>
  );
}

Prop

Type

Key Names

Supported key names for bindings:

  • Special keys: enter, escape, tab, backspace, delete, up, down, left, right, pageup, pagedown, home, end
  • Character keys: a, b, j, k, ?, etc.
  • Modified keys: ctrl+c, ctrl+q, etc.

Key normalization handles variants like ctrl+c, Ctrl-C, ^c automatically.

On this page