giggles

Getting Started

A framework for building interactive terminal user interfaces with React and Ink

giggles is a framework for building interactive terminal user interfaces (TUIs) with React and Ink. It provides a declarative, composable system for handling focus navigation and keyboard input in terminal applications.

Installation

Install giggles along with its peer dependencies:

npm install giggles ink react
pnpm add giggles ink react
yarn add giggles ink react

Verify requirements:

  • Node.js 16+
  • React 18+ or 19+
  • Ink 6+

Your First TUI

Here's a simple menu with keyboard navigation:

app.tsx
import { Box, Text, render, useApp } from 'ink';
import { GigglesProvider, FocusGroup, useFocus, useKeybindings } from 'giggles';

function App() {
  const { exit } = useApp();
  const focus = useFocus();

  useKeybindings(focus, {
    q: () => exit(),
  });

  return (
    <Box flexDirection="column">
      <Text bold>My Menu (j/k to navigate, q to quit)</Text>
      <FocusGroup direction="vertical">
        <Text>Start Game</Text>
        <Text>Settings</Text>
        <Text>Exit</Text>
      </FocusGroup>
    </Box>
  );
}

render(
  <GigglesProvider>
    <App />
  </GigglesProvider>
);

What's happening

  1. GigglesProvider wraps your app and provides focus + input context
  2. FocusGroup creates a navigable group (use j/k or arrow keys)
  3. useFocus() gives your component access to focus state
  4. useKeybindings() binds keys to actions when focused

Next Steps

Core Concepts

Understanding how giggles works

On this page

InstallationYour First TUINext Steps