# GigglesProvider



import { TypeTable } from 'fumadocs-ui/components/type-table';

Root provider for giggles applications. Wrap your app in this to enable focus, input, and theming. By default it sizes the root container to fill the full terminal dimensions and updates automatically on resize. Set `fullScreen={false}` to opt out and let Ink determine the container size.

```tsx title="Basic Setup"
import { render } from 'ink';
import { GigglesProvider } from 'giggles';

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

<TypeTable
  type={{
  children: {
    description: 'Your application components',
    type: 'React.ReactNode',
    required: true,
  },
  theme: {
    description: 'Partial theme overrides. Merged with the default theme.',
    type: 'Partial<GigglesTheme>',
  },
  fullScreen: {
    description: 'Sizes the root container to fill the terminal dimensions, updating on resize.',
    type: 'boolean',
    default: 'true',
  },
}}
/>


# Getting Started



The core systems power giggles' declarative approach to TUI development.

<Cards>
  <Card title="Focus System" description="Tree-based focus management that mirrors your component hierarchy" href="/core/focus" />

  <Card title="Input System" description="Routes keyboard events and prevents input leaking" href="/core/input" />
</Cards>


# Theme



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Swatch } from '@/components/swatch';

ThemeProvider [#themeprovider]

Override theme values for a subtree. Nest multiple providers to apply different themes to different parts of the app. Merges with the parent theme, so you only need to specify the values you want to change.

```tsx title="Nested Themes"
import { GigglesProvider, ThemeProvider } from 'giggles';

render(
  <GigglesProvider theme={{ accentColor: '#6B9FD4' }}>
    <Sidebar />
    <ThemeProvider theme={{ accentColor: '#C97066' }}>
      <MainPanel />
    </ThemeProvider>
  </GigglesProvider>
);
```

<TypeTable
  type={{
  theme: {
    description: 'Partial theme overrides. Merged with the parent theme.',
    type: 'Partial<GigglesTheme>',
  },
  children: {
    description: 'Components that inherit this theme',
    type: 'React.ReactNode',
    required: true,
  },
}}
/>

GigglesTheme [#gigglestheme]

<TypeTable
  type={{
  accentColor: {
    description: 'Color for highlighted items, active indicators, and scroll elements',
    type: 'string',
    default: <Swatch color="#6B9FD4" />,
  },
  borderColor: {
    description: 'Color for component borders (Modal, etc.)',
    type: 'string',
    default: <Swatch color="#5C5C5C" />,
  },
  selectedColor: {
    description: 'Color for checked/selected state indicators',
    type: 'string',
    default: <Swatch color="#8FBF7F" />,
  },
  hintColor: {
    description: 'Color for key labels in CommandPalette hints',
    type: 'string',
    default: <Swatch color="#8A8A8A" />,
  },
  hintDimColor: {
    description: 'Color for command names and separators in CommandPalette hints',
    type: 'string',
    default: <Swatch color="#5C5C5C" />,
  },
  hintHighlightColor: {
    description: 'Color for the highlighted key label in interactive CommandPalette',
    type: 'string',
    default: <Swatch color="#D4D4D4" />,
  },
  hintHighlightDimColor: {
    description: 'Color for the highlighted command name in interactive CommandPalette',
    type: 'string',
    default: <Swatch color="#A0A0A0" />,
  },
  indicator: {
    description: 'Character used for collapsed or inactive state (e.g. closed directory, unselected item)',
    type: 'string',
    default: "'▶'",
  },
  indicatorOpen: {
    description: 'Character used for expanded or active state (e.g. open directory)',
    type: 'string',
    default: "'▼'",
  },
  checkedIndicator: {
    description: 'Character shown for selected items in MultiSelect',
    type: 'string',
    default: "'▣'",
  },
  uncheckedIndicator: {
    description: 'Character shown for unselected items in MultiSelect',
    type: 'string',
    default: "'◻'",
  },
}}
/>

useTheme [#usetheme]

Returns the current `GigglesTheme` from the nearest `ThemeProvider`. Use this in custom `render` functions to stay consistent with the app theme.

```tsx title="Usage"
import { useTheme } from 'giggles';

function CustomOption({ highlighted }: { highlighted: boolean }) {
  const theme = useTheme();
  return <Text color={highlighted ? theme.accentColor : undefined}>...</Text>;
}
```


# Agentic Coding



This page is a reference for AI coding agents (Claude, Cursor, Copilot, etc.) working in a project built with giggles.

Run `npx skills add https://github.com/zion-off/giggles --skill giggles` to install the skill, or copy the block below into your `CLAUDE.md`, `.cursorrules`, or equivalent context file.

````md
## giggles

This project uses giggles — a batteries-included React/Ink framework for terminal UIs. It provides focus management, keyboard input routing, screen navigation, and theming on top of Ink (React for CLIs).

Full documentation is available at https://giggles.zzzzion.com. An index of all pages is available at https://giggles.zzzzion.com/llms.txt — fetch this to discover specific pages before searching for information.

### Setup

Every app wraps with `GigglesProvider`. Never call focus hooks in the same component as the provider — put them in a child component.

```tsx
import { render } from 'ink';
import { GigglesProvider } from 'giggles';

function Root() {
  return (
    <GigglesProvider>
      <App />
    </GigglesProvider>
  );
}

render(<Root />);
```

### Focus primitives

**`useFocusNode(options?)`** — registers a leaf node in the focus tree. Returns `{ id, hasFocus }`. Used directly in custom interactive components. Accepts `focusKey` so the parent scope can address this node via `focusChild`/`focusChildShallow`.

**`useFocusScope(options?)`** — registers a scope node. Returns `{ id, hasFocus, isPassive, next, prev, nextShallow, prevShallow, escape, drillIn, focusChild, focusChildShallow }`.
- `hasFocus` is true when the scope node **or any descendant** has focus (ancestor walk, not strict equality).
- Wrap children in `<FocusScope handle={scope}>` to set the implicit parent for nested hooks. Omitting `<FocusScope>` throws a `GigglesError`.
- `keybindings` accepts a plain object or a factory `(helpers) => object`. Handlers are re-registered every render so closures are never stale.
- `focusKey` — optional string that lets the parent scope address this scope by name via `focusChild`/`focusChildShallow`.

**Navigation helpers** — available directly on the handle and as the `keybindings` factory argument. Stable references; safe to call from effects and event handlers.
```ts
next()                  // move to next child, drill into its first leaf
prev()                  // move to prev child, drill into its first leaf
nextShallow()           // move to next child, land on scope node (don't drill)
prevShallow()           // move to prev child, land on scope node
escape()                // make this scope passive — yields input to parent
drillIn()               // focusFirstChild — queues focus if no children yet; first child to register claims it
focusChild(key)         // focus the direct child registered with focusKey=key, drilling into its first leaf
focusChildShallow(key)  // same, but land on the scope node without drilling
```

### Controlled focus

Use `focusKey` to give a child a stable name, then call `focusChild` from the parent to jump directly to it — bypassing `next`/`prev` iteration. Keys are scoped to the immediate parent scope.

```tsx
// Child declares its key
const scope = useFocusScope({ focusKey: 'editor' });
// or on a UI component:
<TextInput focusKey="search" />

// Parent jumps to it directly
const root = useFocusScope({
  keybindings: ({ focusChild }) => ({
    '1': () => focusChild('files'),
    '2': () => focusChild('editor'),
  })
});

// Also available on the handle for effects
useEffect(() => {
  if (error) root.focusChild('errors');
}, [error]);
```

`focusChild` drills into the first leaf of the target (same as `next`). Use `focusChildShallow` to land on the scope node itself. If the key is not found, both are no-ops. If the target scope has no children yet, `focusChild` queues focus — the first child to register claims it automatically.

### Key bubbling

Keys walk from the focused node up to the root. At each node:
1. Skip if passive.
2. If a binding matches, call it and **stop** — no further bubbling.
3. If this is the trap node, stop.

**Implication for composition:** keys not handled by a UI component bubble to the parent scope. A vertical `Select` consumes `j`/`k`/`↑`/`↓`/`enter` — everything else (e.g. `h`, `l`, `e`) bubbles freely. You only need `escape()` when the same key must serve both an inner and outer scope simultaneously.

### `next` vs `nextShallow`

Use `nextShallow`/`prevShallow` at a scope that contains children which may have no registered descendants (e.g. collapsed tree nodes). `next` drills into children — if a child scope has no registered descendants, it will queue indefinitely. `nextShallow` lands on the scope node itself, where the user can press a key to open it.

### Passive mode

Call `escape()` to make a scope passive. The scope node receives focus and is skipped during dispatch, so parent bindings fire instead. Passive clears automatically when focus leaves the scope's subtree.

Only use passive mode when parent and child scopes compete for the **same keys**. If different keys are used at each level, normal bubbling separates them — no `escape()` needed.

### Border color convention

```tsx
<Box borderColor={scope.isPassive ? 'yellow' : scope.hasFocus ? 'green' : 'grey'}>
```

### UI components (`giggles/ui`)

All interactive components use `useFocusNode()` internally — they are leaf nodes, not scopes. Their keybindings fire before bubbling to any parent scope. All interactive components accept a `focusKey` prop so their parent scope can address them via `focusChild`/`focusChildShallow`.

Available components: `Select`, `MultiSelect`, `TextInput`, `Autocomplete`, `Confirm`, `Viewport`, `Modal`, `Badge`, `Spinner`, `Paginator`, `Panel`, `Markdown`, `VirtualList`, `CommandPalette`, `CodeBlock`.

Key behaviour for interactive components:

| Component | Keys consumed | Notes |
|---|---|---|
| `Select` (vertical) | `j` `k` `↑` `↓` `enter` | All other keys bubble |
| `Select` (horizontal) | `h` `l` `←` `→` `enter` | All other keys bubble |
| `MultiSelect` (vertical) | `j` `k` `↑` `↓` `space`; `enter` if `onSubmit` set | |
| `TextInput` | All printable, `←` `→` `home` `end` `backspace` `delete` `enter` | Passthroughs: `tab` `shift+tab` `escape` |
| `Autocomplete` | All printable, `←` `→` `home` `end` `backspace` `delete` `enter` | Passthroughs: `tab` `shift+tab` `escape` |
| `Confirm` | `y` `n` `enter` | |
| `Viewport` | `j` `k` `↑` `↓` `pageup` `pagedown` `g` `G` | |
| `Modal` | — | Wraps `FocusTrap`; `escape` closes |

`Select` and `MultiSelect` work in controlled or uncontrolled mode. Pass `value`/`onChange` to own state yourself; omit them to let the component manage it internally. Use `onHighlight` to observe cursor movement without owning state.

### `useKeybindings`

Register keybindings independently from focus scope navigation. You can call it multiple times in the same component — all bindings are active simultaneously, later calls override earlier ones for duplicate keys.

```tsx
// Base navigation
useKeybindings(focus, { j: moveDown, k: moveUp });

// Search mode — fallback intercepts unbound keys; escape bubbles to named bindings above
useKeybindings(focus, searchMode ? { escape: exitSearch } : {}, searchMode ? { fallback: handleInput, bubble: ['escape'] } : undefined);
```

**Fallback handler:** pass `fallback` to catch keys that don't match any named binding — useful for text input. Keys listed in `bubble` skip the fallback and propagate to parent scopes. `TextInput` and `Autocomplete` use this internally.

**App-wide shortcuts:** register them on the root scope — unhandled keys bubble up naturally, so a binding at the root fires whenever no child consumes the key first.

### `FocusTrap`

Locks input to a subtree — nothing outside it receives keys until the trap unmounts. Used internally by `Modal`. Use it directly for custom modal-like components.

### Screen router

```ts
const { push, pop, replace, reset, currentRoute } = useNavigation();

push('screenName', params)    // open on top of stack
pop()                         // return to previous screen
replace('screenName', params) // swap current screen
reset('screenName', params)   // clear stack, show this screen
```

All screens stay mounted but hidden — state is preserved across navigation. Focus position is saved on push and restored on pop. Use `restoreFocus={false}` on `<Screen>` to always focus the first child instead.

### Theme

Access the active theme with `useTheme()`. Override values by passing a `theme` prop to `GigglesProvider`:

```tsx
<GigglesProvider theme={{ borderColor: 'cyan', borderStyle: 'round' }}>
```

### Common pitfalls

| Pitfall | Fix |
|---|---|
| Focus hooks in the same component as `GigglesProvider` | Move them into a child component |
| `useFocusScope()` without a corresponding `<FocusScope>` | Throws `GigglesError` — always render `<FocusScope handle={scope}>` wrapping the children |
| `next()` hangs on a scope with no registered children | Use `nextShallow()` at the parent level |
| `h`/`l` bubbling unexpectedly to parent scope | Vertical `Select` does not consume `h`/`l` — use different keys at each level, or use `escape()` if the same keys must serve both |
| Parent bindings not firing while child is focused | Expected — add `escape()` to the child scope to yield control |
````


# Core Concepts



Building a terminal UI means answering one question over and over: when the user presses a key, what should happen? The answer depends on what's active, where it sits in the component tree, and what screens are on the stack. giggles handles all of this through three connected systems — focus, input routing, and screen navigation.

A component that knows when it's active [#a-component-that-knows-when-its-active]

Start with a single panel. You want it to show a green border when it has focus and a grey one when it doesn't. Call `useFocusNode()` to register the component as a focusable target — it returns a handle with a `hasFocus` boolean you can use directly in your render:

```tsx title="A focusable panel"
function Panel() {
  const focus = useFocusNode();

  return (
    <Box borderStyle="single" borderColor={focus.hasFocus ? 'green' : 'grey'}>
      <Text>Panel content</Text>
    </Box>
  );
}
```

Wrap your application in `GigglesProvider` to activate the focus, input, and theme systems:

```tsx title="Setup"
import { GigglesProvider } from 'giggles';

function App() {
  return (
    <GigglesProvider>
      {/* your app */}
    </GigglesProvider>
  );
}
```

The first component to call `useFocusNode` receives focus automatically. When it unmounts, focus moves to its nearest ancestor — so your app always has an active component.

Navigating between components [#navigating-between-components]

One panel isn't interesting. Add a second one and you immediately have a new problem: how does focus move between them?

This is where `useFocusScope` comes in. A scope groups focusable children and defines the keybindings that move between them:

```tsx title="useFocusScope"
function Layout() {
  const scope = useFocusScope({
    keybindings: ({ next, prev }) => ({
      tab: next,
      'shift+tab': prev,
    })
  });

  return (
    <FocusScope handle={scope}>
      <Panel />
      <Panel />
    </FocusScope>
  );
}
```

`next` and `prev` navigate between children, automatically descending to the first leaf so navigation feels natural without manual coordination. `<FocusScope handle={scope}>` sets the parent context — any `useFocusNode` or `useFocusScope` call inside it registers as a child of this scope.

The scope exposes its own `hasFocus` — true whenever any descendant has focus. Use it for container-level visual indicators:

```tsx title="Scope-level focus indicator"
<Box borderColor={scope.hasFocus ? 'green' : undefined}>
  <FocusScope handle={scope}>
    {children}
  </FocusScope>
</Box>
```

How a keypress reaches its handler [#how-a-keypress-reaches-its-handler]

With two panels, pressing `tab` moves focus. But what actually happens between the keypress and the handler firing?

When a key is pressed, giggles walks up the focus tree from the currently focused component toward the root, checking each node for a matching handler. If the focused component has a binding for that key, it fires and the walk stops. If not, the key bubbles to the parent scope, then the grandparent, and so on — the same pattern as DOM event bubbling, just over the focus tree instead of the element tree ([with one exception](/core/input#keybindingoptions)).

This means deeply nested components naturally take precedence over their parents, and unhandled keys always find their way up. You don't need a special global shortcut API — register app-wide shortcuts on the outermost scope and they'll fire whenever nothing deeper claims the key first:

```tsx title="App-level shortcuts"
const root = useFocusScope({
  keybindings: () => ({
    'ctrl+p': openCommandPalette,
    'ctrl+q': quit,
  })
});
```

Navigating between screens [#navigating-between-screens]

Sometimes you want to show an entirely different view — a detail page, a settings panel, a confirmation dialog — without losing the state of what's behind it. giggles handles this with a screen router: a stack of full-screen views where only the top one is visible, but all of them stay mounted.

Stack operations map directly to what you'd expect:

* `push(name, params)` — open a new screen on top
* `pop()` — close the current screen, return to previous
* `replace(name, params)` — swap the current screen
* `reset(name, params)` — clear the stack and show this screen

All screens in the stack stay mounted but hidden. When you navigate back, the previous screen's state is exactly as you left it — no re-initialization or state loss. This makes back navigation instant and predictable.

Each screen also maintains its own focus state. Pushing a new screen saves where focus was; popping it restores focus to exactly that position.

Routers can be nested — a screen can contain its own `Router` for tabbed layouts or sub-navigation, each managing its own independent stack.

Use `useNavigation()` inside screen components to access these functions:

```tsx title="useNavigation"
function DetailScreen() {
  const { pop, push, currentRoute } = useNavigation();

  return (
    <Box>
      <Text>Viewing {currentRoute.params.id}</Text>
    </Box>
  );
}
```


# Getting Started



import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Terminal } from '@/components/terminal';
import GettingStartedExample from '@/components/examples/framework/getting-started';

giggles is a batteries-included framework for building terminal user interfaces (TUIs) with React and Ink. It handles focus management, input routing, screen navigation, and theming out of the box — along with a component library covering most TUI use cases and terminal utilities for things like handing off control to external programs. Everything is declarative and composable, so you can build polished CLI apps without wiring up the low-level details yourself.

Installation [#installation]

<Steps>
  <Step>
    Scaffold a new project:

    <Tabs items={['npm', 'pnpm', 'yarn']}>
      <Tab value="npm">
        ```bash
        npx create-giggles-app
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm create giggles-app
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn create giggles-app
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

Your First TUI [#your-first-tui]

Here's a simple menu with keyboard navigation:

```tsx title="app.tsx"
import { useState } from 'react';
import { Box, Text, render } from 'ink';
import { GigglesProvider } from 'giggles';
import { Select } from 'giggles/ui';

const menuItems = [
  { label: 'New Game', value: 'new' },
  { label: 'Continue', value: 'continue' },
  { label: 'Settings', value: 'settings' },
  { label: 'Quit', value: 'quit' },
];

function App() {
  const [choice, setChoice] = useState('new');

  return (
    <Box flexDirection="column" gap={1}>
      <Text bold>My App</Text>
      <Select options={menuItems} value={choice} onChange={setChoice} />
      <Text dimColor>Selected: {choice}</Text>
    </Box>
  );
}

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

<Terminal>
  <GettingStartedExample />
</Terminal>

<Callout type="info" title="What's happening">
  1. `GigglesProvider` wraps your app and provides focus + input context
  2. `Select` handles focus, keyboard navigation, and rendering for you
  3. Use `j`/`k` or arrow keys to navigate, `Enter` to confirm
</Callout>


# Motivation



my first ink app was an ai chat app. one input field, one scrollable message list, and a slash command menu. it was perfect, and for some time i was in awe of how react was running in the terminal.

that was a while ago. more recently, i noticed that i kept jumping between a bunch of things at work -- jira, github, teams, my notes, and what not. i already use a terminal ide and lazygit, and i wondered if i could bring the rest to my terminal too. so i started building a [terminal dashboard](https://www.npmjs.com/package/clairo) for personal use. git remotes, pull requests, jira views, notes, ai features, all in one place, across tabs and modals.

when building it, i also added this little easter egg: a rubber duck in the bottom right corner that you could toggle on and off with `d`, and it would print out random quips when you did certain things in the tui, like opening a pr or changing the status of a jira ticket. you could hit `q` to get random sardonic quacks as well.

it was incredible. but then one time when i was typing in a log entry or something, i saw the duck quack in the corner of the screen. i thought it was odd because i hadn't done anything to trigger a duck event, but it was a fleeting thought because i was already in the middle of something else.

it happened a few more times before it finally occured to me that my keypresses in an input field in a completely different part of the app were leaking through to the duck. the other problems i had encountered during development became obvious: how i had to do all sorts of gymnastics to manage focus between the different tabs, panels, and modals, manage navigation state and routing by hand, and deal with outdated ui components incompatible with newer ink versions.

and i wondered... is everyone doing all this plumbing themselves, everytime they build an ink app?

ink is terrific at what it does, and it offers the perfect set of primitives that anyone can build on top of. but its ecosystem is very much a do-it-yourself one. you set up focus, navigation, and keybindings, and, besides the components that ink ships with, you build the rest of the ui components yourself.

since my first ink app, i had built a few more tuis with charmbracelet's [bubbletea](https://github.com/charmbracelet/bubbletea), [bubbles](https://github.com/charmbracelet/bubbles), and [lipgloss](https://github.com/charmbracelet/lipgloss), which offer a more batteries-included experience. its elm inspired architecture aligns perfectly with terminal apps, and their ui components allow you to end up with a great looking terminal app without taking on too many styling concerns. and i thought... i want this for ink and react.

something that sits on top of ink and does the groundwork for me, so i can hit the ground running without having to worry about the low level circuitry. this is, essentially, how giggles was born. a framework with sensible defaults and the flexibility to customize and build on top of them whenever you need to. its the structural layer on top of ink, and you use both together to build your app.

remember to giggle while you ink!


# Terminal



import { TypeTable } from 'fumadocs-ui/components/type-table';

Hooks and components for reactive terminal dimensions, OS-level focus detection, and handing terminal control to external programs.

These are imported from `giggles/terminal` — a separate entry point not included in the main bundle.

```tsx title="Import"
import { useTerminalSize, useTerminalFocus, useShellOut, useSpawn } from 'giggles/terminal';
```

API Reference [#api-reference]

useTerminalSize() [#useterminalsize]

Returns reactive terminal dimensions that update on resize.

```ts title="Type Signature"
function useTerminalSize(): TerminalSize
```

**Returns:** `TerminalSize`

<TypeTable
  type={{
  rows: {
    description: 'Number of rows in the terminal',
    type: 'number',
    required: true,
  },
  columns: {
    description: 'Number of columns in the terminal',
    type: 'number',
    required: true,
  },
}}
/>

useTerminalFocus() [#useterminalfocus]

Detects when the terminal window gains or loses OS-level focus.

```ts title="Type Signature"
function useTerminalFocus(callback: (focused: boolean) => void): void
```

Opts into ANSI focus reporting (`\x1b[?1004h`). The terminal emits a sequence when the user switches to another app and back. Not all terminal emulators support this — test for your target environment.

<TypeTable
  type={{
  callback: {
    description: 'Called with true when the terminal gains focus, false when it loses focus',
    type: '(focused: boolean) => void',
    required: true,
  },
}}
/>

useShellOut() [#useshellout]

Hands terminal control to an external program and reclaims it when the process exits.

```ts title="Type Signature"
function useShellOut(): { run: (command: string) => Promise<{ exitCode: number }> }
```

`run()` handles the full sequence: leaves the alternate screen, releases stdin/stdout to the child process with `stdio: 'inherit'`, waits for exit, then reclaims control and repaints. Getting this sequence wrong leaves the terminal in a broken state — use this instead of spawning processes manually.

`run()` never throws on non-zero exit codes. Check `exitCode` in the result if you need to act on failure.

<TypeTable
  type={{
  run: {
    description: 'Runs a shell command with full terminal control. Returns the exit code when the process exits.',
    type: '(command: string) => Promise<{ exitCode: number }>',
    required: true,
  },
}}
/>

useSpawn() [#usespawn]

Spawns a child process and streams its output into React state while the TUI stays live.

```ts title="Type Signature"
function useSpawn(): SpawnHandle
```

Unlike `useShellOut`, the TUI keeps rendering while the process runs — output arrives incrementally via `output`. Call `run()` to spawn a process; calling it again while a process is already running kills the previous one first. The process is killed automatically on unmount.

**Returns:** `SpawnHandle`

<TypeTable
  type={{
  run: {
    description: 'Spawns a process. Kills any currently running process before starting the new one.',
    type: '(command: string, args?: string[], options?: SpawnOptions) => void',
    required: true,
  },
  output: {
    description: 'Ordered list of lines received from the process. Cleared each time run() is called.',
    type: 'SpawnOutputLine[]',
    required: true,
  },
  running: {
    description: 'True while the process is alive. Becomes false once the process exits, errors, or is killed.',
    type: 'boolean',
    required: true,
  },
  exitCode: {
    description: 'The exit code once the process has exited. Null while running or if the process was killed by a signal.',
    type: 'number | null',
    required: true,
  },
  error: {
    description: 'Set if the process failed to start or emitted a Node.js error event (e.g. ENOENT). Cleared on each run() call.',
    type: 'Error | null',
    required: true,
  },
  kill: {
    description: 'Sends SIGTERM to the process and immediately sets running to false.',
    type: '() => void',
    required: true,
  },
}}
/>

**`SpawnOutputLine`**

<TypeTable
  type={{
  type: {
    description: 'Which stream the data came from.',
    type: "'stdout' | 'stderr'",
    required: true,
  },
  data: {
    description: 'Raw string chunk as received from the stream. May contain partial lines or ANSI escape codes.',
    type: 'string',
    required: true,
  },
}}
/>

**Options**

All options from Node's `child_process.spawn` are accepted, plus:

<TypeTable
  type={{
  pty: {
    description: 'Injects FORCE_COLOR=1 and TERM=xterm-256color into the child environment so tools that detect isTTY emit ANSI color codes.',
    type: 'boolean',
    default: 'false',
  },
}}
/>

Examples [#examples]

Responsive layout [#responsive-layout]

```tsx title="Responsive Sidebar"
import { useTerminalSize } from 'giggles/terminal';
import { Box } from 'ink';

function App() {
  const { columns } = useTerminalSize();

  return (
    <Box>
      {columns > 80 && <Sidebar />}
      <MainContent />
    </Box>
  );
}
```

Pause on blur [#pause-on-blur]

```tsx title="Pause on Blur"
import { useTerminalFocus } from 'giggles/terminal';
import { useState } from 'react';
import { Text } from 'ink';

function Timer() {
  const [paused, setPaused] = useState(false);

  useTerminalFocus((focused) => {
    setPaused(!focused);
  });

  return <Text>{paused ? 'Paused' : 'Running'}</Text>;
}
```

Stream command output [#stream-command-output]

```tsx title="Docker Logs"
import { useFocusScope, useKeybindings } from 'giggles';
import { useSpawn } from 'giggles/terminal';
import { Box, Text } from 'ink';

function DockerLogs({ container }: { container: string }) {
  const scope = useFocusScope();
  const { output, running, error, run, kill } = useSpawn();

  useKeybindings(scope, {
    r: () => run('docker', ['logs', '-f', container], { pty: true }),
    k: kill,
  });

  return (
    <Box flexDirection="column">
      {error && <Text color="red">{error.message}</Text>}
      {output.map((line, i) => (
        <Text key={i}>{line.data}</Text>
      ))}
      {running && <Text dimColor>Tailing logs… (k to stop)</Text>}
      {!running && !error && <Text dimColor>r to tail logs</Text>}
    </Box>
  );
}
```

Open $EDITOR [#open-editor]

```tsx title="Edit a File"
import { useFocusScope, useKeybindings } from 'giggles';
import { useShellOut } from 'giggles/terminal';
import { Text } from 'ink';

function FileViewer({ path }: { path: string }) {
  const scope = useFocusScope();
  const shell = useShellOut();

  useKeybindings(scope, {
    e: async () => {
      await shell.run(`${process.env.EDITOR ?? 'vim'} ${path}`);
    },
  });

  return <Text dimColor>Press e to edit {path}</Text>;
}
```


# Autocomplete



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Callout } from 'fumadocs-ui/components/callout';
import { Terminal } from '@/components/terminal';
import AutocompleteExample from '@/components/examples/ui/autocomplete';

A searchable select list. Type to filter options, navigate with arrow keys, and confirm with Enter.

Filtering uses smart case matching by default — all-lowercase queries are case-insensitive, but if any uppercase character is present the search becomes case-sensitive. Provide a custom `filter` function to override this behavior.

The `value` prop represents the selected option, not the search query. The search query is managed internally and resets the highlight index whenever it changes.

```tsx title="Basic Usage"
import { Autocomplete } from 'giggles/ui';
import { useState } from 'react';

const countries = [
  { label: 'Argentina', value: 'ar' },
  { label: 'Brazil', value: 'br' },
  { label: 'Canada', value: 'ca' },
];

function CountryPicker() {
  const [country, setCountry] = useState('ar');

  return (
    <Autocomplete
      label="Country:"
      placeholder="Search..."
      options={countries}
      value={country}
      onChange={setCountry}
    />
  );
}
```

<Terminal>
  <AutocompleteExample />
</Terminal>

<Callout>
  Option values must be unique. Duplicate values will throw a `GigglesError`. Use primitive types (strings, numbers) for option values — object references are compared with `===`.
</Callout>

API Reference [#api-reference]

Autocomplete [#autocomplete]

<TypeTable
  type={{
  options: {
    description: 'List of options to choose from',
    type: 'SelectOption<T>[]',
    required: true,
  },
  value: {
    description: 'Currently selected value (controlled)',
    type: 'T',
    required: true,
  },
  onChange: {
    description: 'Called with the new value when an option is confirmed with Enter',
    type: '(value: T) => void',
    required: true,
  },
  onSubmit: {
    description: 'Called with the selected value after onChange when Enter is pressed',
    type: '(value: T) => void',
  },
  onHighlight: {
    description: 'Called when the highlight moves to a different option',
    type: '(value: T) => void',
  },
  label: {
    description: 'Text displayed before the search input',
    type: 'string',
  },
  placeholder: {
    description: 'Text shown when the search input is empty and unfocused',
    type: 'string',
  },
  filter: {
    description: 'Custom filter function. Receives the current query and an option, returns whether to include it. Defaults to smart case substring matching.',
    type: '(query: string, option: SelectOption<T>) => boolean',
  },
  gap: {
    description: 'Vertical spacing between options (in lines)',
    type: 'number',
    default: '0',
  },
  maxVisible: {
    description: 'Maximum number of options visible at once. When set, the list scrolls to keep the highlighted option in view.',
    type: 'number',
  },
  paginatorStyle: {
    description: 'Style of the scroll indicator when maxVisible is set',
    type: "'dots' | 'arrows' | 'scrollbar' | 'counter' | 'none'",
    default: "'dots'",
  },
  wrap: {
    description: 'Wrap navigation from the last item back to the first (and vice versa)',
    type: 'boolean',
    default: 'true',
  },
  render: {
    description: 'Custom render function for each option row. Replaces the default rendering entirely.',
    type: '(props: AutocompleteRenderProps<T>) => React.ReactNode',
  },
  focusKey: {
    description: 'Key used to address this component from its parent scope via focusChild/focusChildShallow.',
    type: 'string',
  },
}}
/>

Keybindings [#keybindings]

| Key                 | Action                            |
| ------------------- | --------------------------------- |
| Characters          | Type to filter options            |
| `↑` / `↓`           | Highlight previous/next option    |
| `←` / `→`           | Move cursor in search input       |
| `Home` / `End`      | Jump to start/end of search input |
| `Backspace`         | Delete character before cursor    |
| `Delete`            | Delete character at cursor        |
| `Enter`             | Confirm highlighted option        |
| `Tab` / `Shift+Tab` | Move to next/previous component   |
| `Escape`            | Available for parent keybindings  |

AutocompleteRenderProps [#autocompleterenderprops]

<TypeTable
  type={{
  option: {
    description: 'The option being rendered',
    type: 'SelectOption<T>',
    required: true,
  },
  focused: {
    description: 'Whether the Autocomplete component has focus',
    type: 'boolean',
    required: true,
  },
  highlighted: {
    description: 'Whether this option is the current highlight',
    type: 'boolean',
    required: true,
  },
  selected: {
    description: 'Whether this option matches the current value',
    type: 'boolean',
    required: true,
  },
}}
/>

Examples [#examples]

Custom filter [#custom-filter]

```tsx title="Custom Filter"
<Autocomplete
  options={items}
  value={selected}
  onChange={setSelected}
  filter={(query, option) =>
    option.label.startsWith(query)
  }
/>
```

Custom render [#custom-render]

```tsx title="Custom Render"
<Autocomplete
  options={options}
  value={selected}
  onChange={setSelected}
  render={({ option, highlighted, selected }) => (
    <Text color={highlighted ? 'cyan' : 'white'} bold={selected}>
      {highlighted ? '→' : ' '} {option.label}
    </Text>
  )}
/>
```


# Badge



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Terminal } from '@/components/terminal';
import BadgeExample from '@/components/examples/ui/badge';

A styled inline label with powerline-inspired glyph borders.

Badge renders text with a colored background and optional decorative edges. Three variants are available: `round` uses rounded powerline glyphs, `arrow` uses angled glyphs, and `plain` renders a simple padded block with no glyphs.

Colors default to the theme's `accentColor` for the background and black for the text. Override with the `color` and `background` props.

```tsx title="Basic Usage"
import { Badge } from 'giggles/ui';

function StatusBar() {
  return (
    <Box gap={1}>
      <Badge>stable</Badge>
      <Badge background="#E06C75">error</Badge>
      <Badge variant="arrow">deploy</Badge>
    </Box>
  );
}
```

<Terminal>
  <BadgeExample />
</Terminal>

API Reference [#api-reference]

Badge [#badge]

<TypeTable
  type={{
  children: {
    description: 'Text content of the badge',
    type: 'string',
    required: true,
  },
  color: {
    description: 'Text color',
    type: 'string',
    default: "'#000000'",
  },
  background: {
    description: 'Background color',
    type: 'string',
    default: 'theme.accentColor',
  },
  variant: {
    description: 'Glyph style for the badge edges',
    type: "'round' | 'arrow' | 'plain'",
    default: "'round'",
  },
}}
/>


# CodeBlock



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Callout } from 'fumadocs-ui/components/callout';
import { Terminal } from '@/components/terminal';
import { Swatch } from '@/components/swatch';
import CodeBlockExample from '@/components/examples/ui/codeblock';

A syntax-highlighted code block powered by Prism.

CodeBlock tokenizes source code and renders each token with a color based on its type — keywords, strings, comments, functions, and more. Languages are not bundled by default. Import the Prism grammar for any language you need, and CodeBlock picks it up automatically. If a language isn't loaded, the code renders as plain text.

Prism ships with `javascript`, `css`, `markup`, and `clike` built into the core — those work without any imports.

```tsx title="Basic Usage"
import { CodeBlock } from 'giggles/ui';
import 'prismjs/components/prism-typescript';

function Preview() {
  const code = `const x: number = 42;`;

  return <CodeBlock language="typescript">{code}</CodeBlock>;
}
```

<Terminal>
  <CodeBlockExample />
</Terminal>

<Callout type="warn">
  Import language grammars after any `giggles/ui` import so that `prismjs` is initialized before grammars attempt to register themselves. The formatter setup in `create-giggles-app` automatically handles this ordering for you.
</Callout>

API Reference [#api-reference]

CodeBlock [#codeblock]

<TypeTable
  type={{
  children: {
    description: 'Source code string to render',
    type: 'string',
    required: true,
  },
  language: {
    description: 'Prism language identifier (e.g. "typescript", "python", "rust"). The grammar must be imported separately.',
    type: 'string',
  },
  tokenColors: {
    description: 'Override individual token colors',
    type: 'Partial\<TokenColors\>',
  },
  borderStyle: {
    description: 'Border style of the root container.',
    type: 'string',
    default: 'theme.borderStyle',
  },
  paddingX: {
    description: 'Horizontal padding inside the root container.',
    type: 'number',
    default: '1',
  },
  borderColor: {
    description: 'Border color of the root container.',
    type: 'string',
    default: 'theme.borderColor',
  },
  '...boxProps': {
    description: 'All Ink BoxProps are accepted and spread onto the root container.',
    type: 'BoxProps',
  },
}}
/>

TokenColors [#tokencolors]

<TypeTable
  type={{
  keyword: {
    description: 'Keywords, tags, booleans',
    type: 'string',
    default: <Swatch color="#C678DD" />,
  },
  string: {
    description: 'Strings, template strings, attribute values',
    type: 'string',
    default: <Swatch color="#98C379" />,
  },
  number: {
    description: 'Numeric literals',
    type: 'string',
    default: <Swatch color="#D19A66" />,
  },
  comment: {
    description: 'Comments, docstrings',
    type: 'string',
    default: <Swatch color="#5C6370" />,
  },
  function: {
    description: 'Function names, attribute names',
    type: 'string',
    default: <Swatch color="#61AFEF" />,
  },
  operator: {
    description: 'Operators, arrows',
    type: 'string',
    default: <Swatch color="#56B6C2" />,
  },
  punctuation: {
    description: 'Brackets, semicolons, commas',
    type: 'string',
    default: <Swatch color="#ABB2BF" />,
  },
  builtin: {
    description: 'Built-in types, constants, symbols',
    type: 'string',
    default: <Swatch color="#E5C07B" />,
  },
  className: {
    description: 'Class, type, and namespace names',
    type: 'string',
    default: <Swatch color="#E5C07B" />,
  },
  variable: {
    description: 'Variables',
    type: 'string',
    default: <Swatch color="#E06C75" />,
  },
  property: {
    description: 'Object properties',
    type: 'string',
    default: <Swatch color="#E06C75" />,
  },
  regex: {
    description: 'Regular expressions',
    type: 'string',
    default: <Swatch color="#98C379" />,
  },
  inserted: {
    description: 'Inserted lines in diffs',
    type: 'string',
    default: <Swatch color="#98C379" />,
  },
  deleted: {
    description: 'Deleted lines in diffs',
    type: 'string',
    default: <Swatch color="#E06C75" />,
  },
}}
/>

Examples [#examples]

Without border [#without-border]

```tsx title="Borderless"
<CodeBlock language="javascript" borderStyle={undefined}>
  {`console.log("hello");`}
</CodeBlock>
```

Custom token colors [#custom-token-colors]

```tsx title="Custom Colors"
<CodeBlock
  language="typescript"
  tokenColors={{ keyword: '#FF79C6', string: '#F1FA8C' }}
>
  {code}
</CodeBlock>
```

Diff [#diff]

```tsx title="Diff"
import 'prismjs/components/prism-diff';

const diff = `- const name = "old";
+ const name = "new";
  const x = 42;`;

<CodeBlock language="diff">{diff}</CodeBlock>
```


# Command Palette



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Terminal } from '@/components/terminal';
import CommandPaletteExample from '@/components/examples/ui/command-palette';

A compact key hints bar that collects all named keybindings registered across the app. In interactive mode, it captures input and lets the user fuzzy-search and execute commands — type to filter, up/down arrow keys to navigate, Enter to execute, Escape to close. In non-interactive mode, it displays available keybindings for the currently focused context.

Components register commands by passing a `name` field to `useKeybindings`. The default UI shows no keybinding hints of its own — use the `render` prop to add them, or display a static `<CommandPalette interactive={false} />` elsewhere in the layout.

```tsx title="Interactive (Search & Execute)"
import { useKeybindings, useFocusScope } from 'giggles';
import { CommandPalette } from 'giggles/ui';
import { useState } from 'react';

function App() {
  const focus = useFocusScope();
  const [showPalette, setShowPalette] = useState(false);

  useKeybindings(focus, {
    'ctrl+k': { action: () => setShowPalette(true), name: 'Open palette' },
  });

  return (
    <>
      <FileList />
      {showPalette && <CommandPalette onClose={() => setShowPalette(false)} />}
    </>
  );
}
```

```tsx title="Non-Interactive (Hints Bar)"
import { CommandPalette } from 'giggles/ui';

function App() {
  return (
    <Box flexDirection="column">
      <Content />
      <CommandPalette interactive={false} />
    </Box>
  );
}
```

<Terminal>
  <CommandPaletteExample />
</Terminal>

API Reference [#api-reference]

CommandPalette [#commandpalette]

<TypeTable
  type={{
  onClose: {
    description: 'Called when the palette should close (Escape key or after executing a command). Required when interactive.',
    type: '() => void',
  },
  interactive: {
    description: 'When true, captures input with a FocusTrap for searching and executing commands. When false, renders a static hints bar showing available keybindings.',
    type: 'boolean',
    default: 'true',
  },
  maxVisible: {
    description: 'Maximum number of commands shown at once. When the list exceeds this, a scrollbar is shown.',
    type: 'number',
    default: '10',
  },
  render: {
    description: 'Custom render function. When provided, replaces the default palette UI entirely. Navigation keybindings (up/down/enter/escape) are handled automatically — use the provided onChange with a TextInput for search input. Only used in interactive mode.',
    type: '(props: CommandPaletteRenderProps) => React.ReactNode',
  },
}}
/>

CommandPaletteRenderProps [#commandpaletterenderprops]

<TypeTable
  type={{
  query: {
    description: 'Current search query string',
    type: 'string',
    required: true,
  },
  onChange: {
    description: 'Update the search query. Pass this to a TextInput to wire up search input.',
    type: '(query: string) => void',
    required: true,
  },
  filtered: {
    description: 'Commands matching the current query',
    type: 'RegisteredKeybinding[]',
    required: true,
  },
  selectedIndex: {
    description: 'Index of the currently highlighted command',
    type: 'number',
    required: true,
  },
  onSelect: {
    description: 'Execute a command and close the palette',
    type: '(cmd: RegisteredKeybinding) => void',
    required: true,
  },
}}
/>

See [`RegisteredKeybinding`](/core/input#registeredkeybinding) on the Input page.


# Confirm



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Terminal } from '@/components/terminal';
import ConfirmExample from '@/components/examples/ui/confirm';

A yes/no prompt. Press `y` to confirm, `n` to decline, or Enter to accept the default.

The `defaultValue` prop controls which option is pre-selected. The hint text updates to reflect this — `(Y/n)` when defaulting to yes, `(y/N)` when defaulting to no. Unlike Select, Confirm is a one-shot interaction: `onSubmit` fires once with a boolean and there's no controlled value state.

`Confirm` is a leaf focus node. When used alongside other interactive components (e.g. a `Select`), wrap it in a `Modal` so that `FocusTrap` steals focus away and `y`/`n`/`Enter` reach it reliably.

```tsx title="Basic Usage"
import { Confirm } from 'giggles/ui';

function DeletePrompt() {
  return (
    <Confirm
      message="Delete this file?"
      onSubmit={(yes) => {
        if (yes) deleteFile();
      }}
    />
  );
}
```

<Terminal>
  <ConfirmExample />
</Terminal>

API Reference [#api-reference]

Confirm [#confirm]

<TypeTable
  type={{
  message: {
    description: 'The question to display',
    type: 'string',
    required: true,
  },
  onSubmit: {
    description: 'Called with true (yes) or false (no) when the user answers',
    type: '(value: boolean) => void',
    required: true,
  },
  defaultValue: {
    description: 'Which option Enter selects. Affects the hint text shown.',
    type: 'boolean',
    default: 'true',
  },
  focusKey: {
    description: 'Key used to address this component from its parent scope via focusChild/focusChildShallow.',
    type: 'string',
  },
}}
/>

Keybindings [#keybindings]

| Key     | Action         |
| ------- | -------------- |
| `y`     | Confirm (yes)  |
| `n`     | Decline (no)   |
| `Enter` | Accept default |

Examples [#examples]

Default to no [#default-to-no]

```tsx title="Default to No"
<Confirm
  message="Reset all settings?"
  defaultValue={false}
  onSubmit={(yes) => {
    if (yes) resetSettings();
  }}
/>
```


# Components



Styled components with sensible defaults. Each component handles focus, keybindings, and rendering automatically.

For components where rendering genuinely varies, a `render` prop gives full control over the visual output. The terminal's styling surface area is small enough that props cover the vast majority of customization needs.

Components [#components]

| Component                              | Description                                      |
| -------------------------------------- | ------------------------------------------------ |
| [TextInput](/ui/text-input)            | Single-line text input with cursor navigation    |
| [Select](/ui/select)                   | Single-select list with keyboard navigation      |
| [MultiSelect](/ui/multi-select)        | Multi-select list with checkboxes                |
| [Confirm](/ui/confirm)                 | Yes/no confirmation prompt                       |
| [Autocomplete](/ui/autocomplete)       | Filterable select with text input                |
| [Badge](/ui/badge)                     | Styled inline label with powerline glyphs        |
| [CodeBlock](/ui/codeblock)             | Syntax-highlighted code block                    |
| [Panel](/ui/panel)                     | Titled box with inline border header             |
| [Markdown](/ui/markdown)               | Terminal markdown renderer                       |
| [VirtualList](/ui/virtual-list)        | Windowed list rendering for large datasets       |
| [Viewport](/ui/viewport)               | Scrollable content container                     |
| [Paginator](/ui/paginator)             | Scroll position indicator                        |
| [Modal](/ui/modal)                     | Focus-trapping container with border and title   |
| [Command Palette](/ui/command-palette) | Fuzzy-searchable list of all registered commands |


# Markdown



import { TypeTable } from 'fumadocs-ui/components/type-table';

A terminal markdown renderer.

Markdown parses a string and renders it with styled Ink components. Supports headings, bold, italic, inline code, code blocks, links, images, blockquotes, ordered and unordered lists, tables, horizontal rules, and strikethrough. Tables are rendered using box-drawing characters. Links are clickable in terminals that support OSC 8.

Colors are pulled from the theme — `accentColor` for inline code and links, `borderColor` for code block borders and table frames.

```tsx title="Basic Usage"
import { Markdown } from 'giggles/markdown';

function HelpScreen() {
  const helpText = `# Shortcuts

  - **q** to quit
  - **?** for help

  > Press any key to continue.`;

  return <Markdown>{helpText}</Markdown>;
}
```

API Reference [#api-reference]

Markdown [#markdown]

<TypeTable
  type={{
  children: {
    description: 'Markdown string to render',
    type: 'string',
    required: true,
  },
}}
/>

Examples [#examples]

Code blocks [#code-blocks]

```tsx title="Code Block"
const md = `
\`\`\`ts
const x = 42;
\`\`\`
`;

<Markdown>{md}</Markdown>
```

Tables [#tables]

```tsx title="Table"
const md = `
| Command | Description |
| ------- | ----------- |
| q       | Quit        |
| ?       | Help        |
`;

<Markdown>{md}</Markdown>
```


# Modal



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Callout } from 'fumadocs-ui/components/callout';
import { Terminal } from '@/components/terminal';
import ModalExample from '@/components/examples/ui/modal';

A focus-trapping container with a border and optional title. When rendered, Modal captures all focus and keyboard input. Press Escape to close. When the modal unmounts, focus returns to the previously focused component.

Render it conditionally — Modal takes over input the moment it mounts. Put any content inside: text, forms, lists, or other interactive components.

```tsx title="Basic Usage"
import { Modal } from 'giggles/ui';
import { useState } from 'react';

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

  return (
    <>
      <MainContent />
      {showModal && (
        <Modal title="Confirm" onClose={() => setShowModal(false)}>
          <Text>Are you sure?</Text>
        </Modal>
      )}
    </>
  );
}
```

<Terminal>
  <ModalExample />
</Terminal>

<Callout>
  Modal captures all input while open. Register the keybinding that opens the modal on a scope that sits above the modal's children — unhandled keys bubble up naturally, so it will fire regardless of which child currently has focus.
</Callout>

API Reference [#api-reference]

Modal [#modal]

<TypeTable
  type={{
  children: {
    description: 'Content rendered inside the modal',
    type: 'React.ReactNode',
    required: true,
  },
  onClose: {
    description: 'Called when Escape is pressed',
    type: '() => void',
    required: true,
  },
  title: {
    description: 'Bold text rendered at the top of the modal',
    type: 'string',
  },
  borderStyle: {
    description: 'Border style of the modal container.',
    type: 'string',
    default: 'theme.borderStyle',
  },
  alignSelf: {
    description: 'Aligns the modal along the cross axis.',
    type: 'string',
    default: '"flex-start"',
  },
  paddingX: {
    description: 'Horizontal padding inside the modal container.',
    type: 'number',
    default: '1',
  },
  borderColor: {
    description: 'Border color of the modal container.',
    type: 'string',
    default: 'theme.borderColor',
  },
  '...boxProps': {
    description: 'All Ink BoxProps are accepted and spread onto the root container.',
    type: 'BoxProps',
  },
}}
/>

Keybindings [#keybindings]

| Key      | Action          |
| -------- | --------------- |
| `Escape` | Close the modal |

Examples [#examples]

Modal with interactive content [#modal-with-interactive-content]

```tsx title="Modal with Form"
{showModal && (
  <Modal title="New File" onClose={() => setShowModal(false)}>
    <TextInput label="Filename:" value={name} onChange={setName} onSubmit={createFile} />
  </Modal>
)}
```


# MultiSelect



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Callout } from 'fumadocs-ui/components/callout';
import { Terminal } from '@/components/terminal';
import MultiSelectExample from '@/components/examples/ui/multi-select';

A multi-select list.

Works in controlled or uncontrolled mode. Pass `value` and `onChange` to own the selection state yourself; omit them to let the component manage it internally — starting with nothing selected. Use `onSubmit` to handle a final confirmation on Enter.

```tsx title="Basic Usage"
import { MultiSelect } from 'giggles/ui';

const toppings = [
  { label: 'Pepperoni', value: 'pepperoni' },
  { label: 'Mushrooms', value: 'mushrooms' },
  { label: 'Onions', value: 'onions' },
  { label: 'Olives', value: 'olives' },
];

// uncontrolled — no useState needed
function ToppingPicker() {
  return <MultiSelect options={toppings} onSubmit={(selected) => saveOrder(selected)} />;
}

// controlled — caller owns selection state
function ControlledToppingPicker() {
  const [selected, setSelected] = useState<string[]>([]);
  return <MultiSelect options={toppings} value={selected} onChange={setSelected} />;
}
```

<Terminal>
  <MultiSelectExample />
</Terminal>

<Callout>
  Option values must be unique. Duplicate values will throw a `GigglesError`. Use primitive types (strings, numbers) for option values — items are matched using `===`.
</Callout>

API Reference [#api-reference]

MultiSelect [#multiselect]

<TypeTable
  type={{
  options: {
    description: 'List of options to choose from',
    type: 'SelectOption<T>[]',
    required: true,
  },
  value: {
    description: 'Array of currently selected values. When provided, the component is controlled and the caller owns selection state.',
    type: 'T[]',
  },
  onChange: {
    description: 'Called with the updated array when an item is toggled. Required when value is provided.',
    type: '(value: T[]) => void',
  },
  onSubmit: {
    description: 'Called with the current selections when Enter is pressed. When not provided, Enter is available for parent keybindings.',
    type: '(value: T[]) => void',
  },
  onHighlight: {
    description: 'Called when the highlight moves to a different option',
    type: '(value: T) => void',
  },
  label: {
    description: 'Text displayed above the list',
    type: 'string',
  },
  direction: {
    description: 'Layout direction and navigation key scheme',
    type: "'vertical' | 'horizontal'",
    default: "'vertical'",
  },
  gap: {
    description: 'Vertical spacing between options (in lines)',
    type: 'number',
    default: '0',
  },
  maxVisible: {
    description: 'Maximum number of options visible at once. When set, the list scrolls to keep the highlighted option in view.',
    type: 'number',
  },
  paginatorStyle: {
    description: 'Style of the scroll indicator when maxVisible is set',
    type: "'dots' | 'arrows' | 'scrollbar' | 'counter' | 'none'",
    default: "'dots'",
  },
  wrap: {
    description: 'Wrap navigation from the last item back to the first (and vice versa)',
    type: 'boolean',
    default: 'true',
  },
  render: {
    description: 'Custom render function for each option. Replaces the default rendering entirely.',
    type: '(props: MultiSelectRenderProps<T>) => React.ReactNode',
  },
  focusKey: {
    description: 'Key used to address this component from its parent scope via focusChild/focusChildShallow.',
    type: 'string',
  },
}}
/>

Keybindings [#keybindings]

| Key                 | Action                          |
| ------------------- | ------------------------------- |
| `j` / `↓`           | Highlight next (vertical)       |
| `k` / `↑`           | Highlight previous (vertical)   |
| `l` / `→`           | Highlight next (horizontal)     |
| `h` / `←`           | Highlight previous (horizontal) |
| `Space`             | Toggle highlighted item         |
| `Enter`             | Fire `onSubmit` if provided     |
| `Tab` / `Shift+Tab` | Move to next/previous component |

MultiSelectRenderProps [#multiselectrenderprops]

<TypeTable
  type={{
  option: {
    description: 'The option being rendered',
    type: 'SelectOption<T>',
    required: true,
  },
  focused: {
    description: 'Whether the MultiSelect component has focus',
    type: 'boolean',
    required: true,
  },
  highlighted: {
    description: 'Whether this option is the current highlight',
    type: 'boolean',
    required: true,
  },
  selected: {
    description: 'Whether this option is in the value array',
    type: 'boolean',
    required: true,
  },
}}
/>

Examples [#examples]

With submit [#with-submit]

```tsx title="With Submit"
function FeaturePicker() {
  const [features, setFeatures] = useState<string[]>([]);

  return (
    <MultiSelect
      options={allFeatures}
      value={features}
      onChange={setFeatures}
      onSubmit={(selected) => saveFeatures(selected)}
    />
  );
}
```

Custom render [#custom-render]

```tsx title="Custom Render"
<MultiSelect
  options={options}
  value={selected}
  onChange={setSelected}
  render={({ option, highlighted, selected }) => (
    <Text color={highlighted ? 'cyan' : 'white'}>
      {highlighted ? '>' : ' '} {selected ? '◉' : '○'} {option.label}
    </Text>
  )}
/>
```


# Paginator



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Terminal } from '@/components/terminal';
import PaginatorDotsExample from '@/components/examples/ui/paginator-dots';
import PaginatorArrowsExample from '@/components/examples/ui/paginator-arrows';
import PaginatorScrollbarExample from '@/components/examples/ui/paginator-scrollbar';
import PaginatorCounterExample from '@/components/examples/ui/paginator-counter';

A scroll position indicator for windowed lists. Supports four display styles: dots, arrows, scrollbar, and counter.

Paginator is a pure display component — it has no focus or interactivity. Pass it the total item count, current scroll offset, and number of visible items. It computes and renders the appropriate indicator. When the total number of items fits within the visible window, Paginator renders nothing.

```tsx title="Standalone Usage"
import { Paginator } from 'giggles/ui';

<Paginator total={100} offset={20} visible={10} style="scrollbar" />
```

Dots [#dots]

Shows a row of `●` dots below the list.

<Terminal>
  <PaginatorDotsExample />
</Terminal>

Arrows [#arrows]

Shows `↑` and `↓` indicators above and below the list when there are items outside the visible window.

<Terminal>
  <PaginatorArrowsExample />
</Terminal>

Scrollbar [#scrollbar]

Shows a vertical bar beside the list with a thumb that tracks scroll position.

<Terminal>
  <PaginatorScrollbarExample />
</Terminal>

Counter [#counter]

Shows a text range like `1–10 of 50` below the list.

<Terminal>
  <PaginatorCounterExample />
</Terminal>

API Reference [#api-reference]

Paginator [#paginator]

<TypeTable
  type={{
  total: {
    description: 'Total number of items in the list',
    type: 'number',
    required: true,
  },
  offset: {
    description: 'Index of the first visible item (scroll position)',
    type: 'number',
    required: true,
  },
  visible: {
    description: 'Number of items currently visible',
    type: 'number',
    required: true,
  },
  style: {
    description: "Display style. Dots show a row of page indicators, arrows show ↑/↓ indicators, scrollbar shows a vertical thumb, counter shows a text range, none hides the indicator.",
    type: "'dots' | 'arrows' | 'scrollbar' | 'counter' | 'none'",
    default: "'arrows'",
  },
  gap: {
    description: 'Vertical spacing to match the item list gap. Used by the scrollbar style to match the total height of the items.',
    type: 'number',
    default: '0',
  },
  position: {
    description: 'Used by the arrows style to render above or below the list. Ignored by scrollbar and counter styles.',
    type: "'above' | 'below'",
  },
}}
/>

PaginatorStyle [#paginatorstyle]

```tsx title="Type Definition"
type PaginatorStyle = 'dots' | 'arrows' | 'scrollbar' | 'counter' | 'none';
```


# Panel



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Terminal } from '@/components/terminal';
import PanelExample from '@/components/examples/ui/panel';

A bordered content container with an optional inline title.

Panel renders a rounded border with an optional title integrated into the top edge. Without a `width`, it fills available space using `flexGrow`. Pass a fixed number or a percentage string like `"50%"` via the `width` BoxProp to control sizing. Long titles are automatically truncated to fit. An optional `footer` is pinned to the bottom of the panel, useful for status text or counts.

```tsx title="Basic Usage"
import { Panel } from 'giggles/ui';

function FileList() {
  return (
    <Panel title="Files" footer={<Text dimColor>3 items</Text>}>
      <Text>index.ts</Text>
      <Text>utils.ts</Text>
      <Text>types.ts</Text>
    </Panel>
  );
}
```

<Terminal>
  <PanelExample />
</Terminal>

API Reference [#api-reference]

Panel [#panel]

<TypeTable
  type={{
  children: {
    description: 'Content rendered inside the panel',
    type: 'React.ReactNode',
    required: true,
  },
  title: {
    description: 'Title displayed in the top border. Long titles are truncated to fit the panel width.',
    type: 'string',
  },
  footer: {
    description: 'Content pinned to the bottom of the panel',
    type: 'React.ReactNode',
  },
  width: {
    description: 'Panel width. Accepts numbers or percentage strings like `"100%"`. Defaults to filling available space.',
    type: 'number | string',
  },
  borderColor: {
    description: 'Border color of the panel. Also controls the title decoration.',
    type: 'string',
    default: 'theme.borderColor',
  },
  '...boxProps': {
    description: 'All Ink BoxProps are accepted and spread onto the root container.',
    type: 'BoxProps',
  },
}}
/>

Examples [#examples]

Side-by-side panels [#side-by-side-panels]

```tsx title="Side-by-Side Panels"
<Box gap={1}>
  <Panel title="Source">
    <Text>main.ts</Text>
  </Panel>
  <Panel title="Output">
    <Text>main.js</Text>
  </Panel>
</Box>
```

Fixed width [#fixed-width]

```tsx title="Fixed Width"
<Panel title="Sidebar" width={30}>
  <Text>Navigation content</Text>
</Panel>
```

Percentage width [#percentage-width]

```tsx title="Percentage Width"
<Panel title="Main" width="100%">
  <Text>Full-width content</Text>
</Panel>
```


# Select



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Callout } from 'fumadocs-ui/components/callout';
import { Terminal } from '@/components/terminal';
import SelectExample from '@/components/examples/ui/select';

A single-select list.

Works in controlled or uncontrolled mode. Pass `value` and `onChange` to own the selection state yourself; omit them to let the component manage it internally. Use `onHighlight` to observe cursor movement without taking ownership of state.

By default, `onChange` fires when Enter is pressed. Set `immediate` to fire `onChange` on every highlight change instead — useful for previewing the selected option as you browse. Use `onSubmit` to handle the final confirmation separately.

The `direction` prop controls both layout and navigation keys. Vertical uses `j`/`k`/`Up`/`Down`, horizontal uses `h`/`l`/`Left`/`Right`.

```tsx title="Basic Usage"
import { Select } from 'giggles/ui';

const languages = [
  { label: 'TypeScript', value: 'ts' },
  { label: 'Rust', value: 'rs' },
  { label: 'Go', value: 'go' },
];

// uncontrolled — no useState needed
function LanguagePicker() {
  return <Select options={languages} onSubmit={(lang) => console.log(lang)} />;
}

// controlled — caller owns selection state
function ControlledLanguagePicker() {
  const [lang, setLang] = useState('ts');
  return <Select options={languages} value={lang} onChange={setLang} />;
}
```

<Terminal>
  <SelectExample />
</Terminal>

<Callout>
  Option values must be unique. Duplicate values will throw a `GigglesError`. Use primitive types (strings, numbers) for option values — object references are compared with `===`.
</Callout>

API Reference [#api-reference]

Select [#select]

<TypeTable
  type={{
  options: {
    description: 'List of options to choose from',
    type: 'SelectOption<T>[]',
    required: true,
  },
  value: {
    description: 'Currently selected value. When provided, the component is controlled and the caller owns selection state.',
    type: 'T',
  },
  onChange: {
    description: 'Called with the new value when a selection is made. Fires on Enter by default, or on every highlight change when immediate is set. Required when value is provided.',
    type: '(value: T) => void',
  },
  onSubmit: {
    description: 'Called with the selected value when Enter is pressed. When immediate is set, this is the only way to distinguish confirmation from browsing.',
    type: '(value: T) => void',
  },
  onHighlight: {
    description: 'Called when the highlight moves to a different option',
    type: '(value: T) => void',
  },
  label: {
    description: 'Text displayed above the list',
    type: 'string',
  },
  immediate: {
    description: 'Fire onChange on every highlight change instead of waiting for Enter',
    type: 'boolean',
    default: 'false',
  },
  direction: {
    description: 'Layout direction and navigation key scheme',
    type: "'vertical' | 'horizontal'",
    default: "'vertical'",
  },
  gap: {
    description: 'Vertical spacing between options (in lines)',
    type: 'number',
    default: '0',
  },
  maxVisible: {
    description: 'Maximum number of options visible at once. When set, the list scrolls to keep the highlighted option in view.',
    type: 'number',
  },
  paginatorStyle: {
    description: 'Style of the scroll indicator when maxVisible is set',
    type: "'dots' | 'arrows' | 'scrollbar' | 'counter' | 'none'",
    default: "'dots'",
  },
  wrap: {
    description: 'Wrap navigation from the last item back to the first (and vice versa)',
    type: 'boolean',
    default: 'true',
  },
  render: {
    description: 'Custom render function for each option. Replaces the default rendering entirely.',
    type: '(props: SelectRenderProps<T>) => React.ReactNode',
  },
  focusKey: {
    description: 'Key used to address this component from its parent scope via focusChild/focusChildShallow.',
    type: 'string',
  },
}}
/>

Keybindings [#keybindings]

| Key                 | Action                          |
| ------------------- | ------------------------------- |
| `j` / `↓`           | Highlight next (vertical)       |
| `k` / `↑`           | Highlight previous (vertical)   |
| `l` / `→`           | Highlight next (horizontal)     |
| `h` / `←`           | Highlight previous (horizontal) |
| `Enter`             | Confirm selection               |
| `Tab` / `Shift+Tab` | Move to next/previous component |

SelectOption [#selectoption]

<TypeTable
  type={{
  label: {
    description: 'Display text for the option',
    type: 'string',
    required: true,
  },
  value: {
    description: 'Value passed to onChange when this option is selected. Must be unique across options. Use primitive types (strings, numbers) — objects are compared by reference.',
    type: 'T',
    required: true,
  },
}}
/>

SelectRenderProps [#selectrenderprops]

<TypeTable
  type={{
  option: {
    description: 'The option being rendered',
    type: 'SelectOption<T>',
    required: true,
  },
  focused: {
    description: 'Whether the Select component has focus',
    type: 'boolean',
    required: true,
  },
  highlighted: {
    description: 'Whether this option is the current highlight',
    type: 'boolean',
    required: true,
  },
  selected: {
    description: 'Whether this option matches the current value',
    type: 'boolean',
    required: true,
  },
}}
/>

Examples [#examples]

Immediate mode with preview [#immediate-mode-with-preview]

```tsx title="Immediate Mode with Preview"
function FileTypePicker() {
  const [type, setType] = useState('json');
  const [preview, setPreview] = useState('');

  return (
    <Box flexDirection="row" gap={2}>
      <Select
        options={fileTypes}
        value={type}
        onChange={setType}
        onHighlight={(v) => setPreview(loadPreview(v))}
        immediate
      />
      <Text>{preview}</Text>
    </Box>
  );
}
```

Custom render [#custom-render]

```tsx title="Custom Render"
<Select
  options={options}
  value={selected}
  onChange={setSelected}
  render={({ option, highlighted, selected }) => (
    <Text color={highlighted ? 'cyan' : 'white'} bold={selected}>
      {highlighted ? '→' : ' '} {option.label}
    </Text>
  )}
/>
```


# Spinner



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Terminal } from '@/components/terminal';
import SpinnerExample from '@/components/examples/ui/spinner';

An animated terminal spinner with a set of built-in presets. Ported from [Bubble Tea's spinner](https://github.com/charmbracelet/bubbles/blob/master/spinner/spinner.go).

`Spinner` cycles through a list of frames at a fixed interval, rendering the current frame as colored text. The animation runs independently per instance, so multiple spinners on screen don't interfere with each other. The `spinner` prop accepts any `SpinnerDef` — use one of the built-in `spinners` presets or supply your own frames and interval.

```tsx title="Basic Usage"
import { Spinner, spinners } from 'giggles/ui';

function LoadingState() {
  return (
    <Box gap={1}>
      <Spinner />
      <Text>Loading…</Text>
    </Box>
  );
}

// Custom spinner
const pulse: SpinnerDef = { frames: ['◐', '◓', '◑', '◒'], interval: 120 };
<Spinner spinner={pulse} color="#E06C75" />
```

<Terminal>
  <SpinnerExample />
</Terminal>

API Reference [#api-reference]

Spinner [#spinner]

<TypeTable
  type={{
  spinner: {
    description: 'Spinner definition to use',
    type: 'SpinnerDef',
    default: 'spinners.line',
  },
  color: {
    description: 'Color of the spinner text',
    type: 'string',
    default: 'theme.accentColor',
  },
}}
/>

SpinnerDef [#spinnerdef]

<TypeTable
  type={{
  frames: {
    description: 'Array of strings to cycle through',
    type: 'string[]',
    required: true,
  },
  interval: {
    description: 'Milliseconds between frame advances',
    type: 'number',
    required: true,
  },
}}
/>

Examples [#examples]

Presets [#presets]

Twelve presets are available via the `spinners` object: `line`, `dot`, `miniDot`, `jump`, `pulse`, `points`, `clock`, `hearts`, `moon`, `meter`, `hamburger`, `ellipsis`.

```tsx title="Using a Preset"
import { Spinner, spinners } from 'giggles/ui';

<Spinner spinner={spinners.dot} />
<Spinner spinner={spinners.moon} color="yellow" />
```


# TextInput



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Terminal } from '@/components/terminal';
import TextInputExample from '@/components/examples/ui/text-input';
import TextInputCustomExample from '@/components/examples/ui/text-input-custom';

A controlled single-line text input with cursor navigation, inline editing, and render prop support.

```tsx title="Basic Usage"
import { TextInput } from 'giggles/ui';
import { useState } from 'react';

function NameInput() {
  const [value, setValue] = useState('');

  return <TextInput label="Name:" value={value} onChange={setValue} placeholder="John Doe" />;
}
```

API Reference [#api-reference]

TextInput [#textinput]

<TypeTable
  type={{
  value: {
    description: 'Current input value (controlled)',
    type: 'string',
  		required: true,
  },
  onChange: {
    description: 'Called with the new value on every edit',
    type: '(value: string) => void',
  		required: true,
  },
  onSubmit: {
    description: 'Called with the current value when Enter is pressed. When not provided, Enter passes through to parent bindings.',
    type: '(value: string) => void',
  },
  label: {
    description: 'Text label displayed before the input',
    type: 'string',
  },
  placeholder: {
    description: 'Text shown when the value is empty. When unfocused, rendered dimmed. When focused, the cursor sits at position 0 of the placeholder text.',
    type: 'string',
  },
  render: {
    description: 'Custom render function. Replaces the default rendering entirely.',
    type: '(props: TextInputRenderProps) => React.ReactNode',
  },
  focusKey: {
    description: 'Key used to address this component from its parent scope via focusChild/focusChildShallow.',
    type: 'string',
  },
}}
/>

Keybindings [#keybindings]

| Key                 | Action                                                                  |
| ------------------- | ----------------------------------------------------------------------- |
| Characters          | Insert at cursor position                                               |
| `←` `→`             | Move cursor                                                             |
| `Home` `End`        | Jump to start/end                                                       |
| `Backspace`         | Delete character before cursor                                          |
| `Delete`            | Delete character at cursor                                              |
| `Tab` / `Shift+Tab` | Move to next/previous field                                             |
| `Enter`             | Fire `onSubmit` if provided, otherwise available for parent keybindings |
| `Escape`            | Ignored (available for parent keybindings)                              |

TextInputRenderProps [#textinputrenderprops]

The `render` prop receives pre-split text segments around the cursor.

<TypeTable
  type={{
  value: {
    description: 'Current input value',
    type: 'string',
    required: true,
  },
  focused: {
    description: 'Whether the input is currently focused',
    type: 'boolean',
    required: true,
  },
  before: {
    description: 'Text before the cursor',
    type: 'string',
    required: true,
  },
  cursorChar: {
    description: 'Character at the cursor position, or a space if at the end',
    type: 'string',
    required: true,
  },
  after: {
    description: 'Text after the cursor',
    type: 'string',
    required: true,
  },
  placeholder: {
    description: 'The placeholder string, if provided. Use this to implement cursor-on-placeholder behaviour in custom renders.',
    type: 'string',
  },
}}
/>

Examples [#examples]

Multi-field form [#multi-field-form]

Wrap multiple `TextInput` fields in a `FocusScope` and wire `tab`/`shift+tab` to `next`/`prev` — `TextInput` bubbles both keys automatically so the scope handles field switching with no extra logic. Put `onSubmit` on the last field to fire on `Enter`:

```tsx title="Multi-field form"
import { FocusScope, useFocusScope } from 'giggles';
import { TextInput } from 'giggles/ui';
import { useState } from 'react';

function ContactForm() {
  const [name, setName] = useState('');
  const [email, setEmail] = useState('');
  const [message, setMessage] = useState('');

  const scope = useFocusScope({
    keybindings: ({ next, prev }) => ({ tab: next, 'shift+tab': prev }),
  });

  return (
    <Box flexDirection="column" gap={1}>
      <FocusScope handle={scope}>
        <TextInput label="Name:" value={name} onChange={setName} placeholder="Jane Doe" />
        <TextInput label="Email:" value={email} onChange={setEmail} placeholder="jane@example.com" />
        <TextInput
          label="Message:"
          value={message}
          onChange={setMessage}
          onSubmit={() => submit({ name, email, message })}
          placeholder="Your message..."
        />
      </FocusScope>
    </Box>
  );
}
```

<Terminal>
  <TextInputExample />
</Terminal>

Custom render [#custom-render]

The `render` prop gives full control over how the input is displayed. The `placeholder` prop is forwarded into render props so custom renders can replicate the cursor-on-placeholder behaviour.

```tsx title="Custom Render"
function SearchBar() {
  const [query, setQuery] = useState('');

  return (
    <TextInput
      value={query}
      onChange={setQuery}
      placeholder="Search components..."
      render={({ before, cursorChar, after, focused, value, placeholder }) => {
        const empty = value.length === 0;

        let content;
        if (focused && empty && placeholder) {
          content = <Text><Text inverse>{placeholder[0]}</Text><Text dimColor>{placeholder.slice(1)}</Text></Text>;
        } else if (focused) {
          content = <Text>{before}<Text inverse>{cursorChar}</Text>{after}</Text>;
        } else {
          content = <Text dimColor={empty}>{empty ? placeholder : value}</Text>;
        }

        return (
          <Box borderStyle="round" borderColor={focused ? 'cyan' : 'gray'} paddingX={1} gap={1} width={36}>
            <Text color={focused ? 'cyan' : 'gray'}>/</Text>
            {content}
          </Box>
        );
      }}
    />
  );
}
```

<Terminal>
  <TextInputCustomExample />
</Terminal>


# Viewport



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Terminal } from '@/components/terminal';
import ViewportExample from '@/components/examples/ui/viewport';

A scrollable container that clips content to a fixed height and scrolls by row. Inspired by [Bubble Tea's viewport](https://github.com/charmbracelet/bubbles/blob/master/viewport/viewport.go) and [ink-scroll-view](https://github.com/ByteLandTechnology/ink-scroll-view).

Pass any children — text, components, mixed content. Viewport measures each child's actual rendered height after terminal wrapping, so long lines that wrap across multiple rows are accounted for correctly without any manual line-splitting. Use the ref to programmatically scroll or jump to a specific child with `scrollToItem`. For a virtualized item-count-based list, see [VirtualList](/ui/virtual-list).

```tsx title="Basic Usage"
import { Viewport } from 'giggles/ui';

function ArticleViewer({ paragraphs }: { paragraphs: string[] }) {
  return (
    <Viewport height={20}>
      {paragraphs.map((p, i) => (
        <Text key={i}>{p}</Text>
      ))}
    </Viewport>
  );
}
```

<Terminal>
  <ViewportExample />
</Terminal>

API Reference [#api-reference]

Viewport [#viewport]

<TypeTable
  type={{
  height: {
    description: 'Viewport height in terminal rows',
    type: 'number',
    required: true,
  },
  children: {
    description: 'Content to display inside the scrollable area',
    type: 'React.ReactNode',
  },
  keybindings: {
    description: 'Whether to bind scroll keybindings (j/k, arrows, page, g/G)',
    type: 'boolean',
    default: 'true',
  },
  footer: {
    description: 'Content rendered below the scrollable area, outside the clipping box — useful for scroll indicators or status lines',
    type: 'React.ReactNode',
  },
  focusKey: {
    description: 'Key used to address this component from its parent scope via focusChild/focusChildShallow.',
    type: 'string',
  },
  '...boxProps': {
    description: 'Any Ink Box prop (borderStyle, borderColor, padding, width, etc.) applied to the outer container. height, overflow, and flexDirection are reserved.',
    type: 'BoxProps',
  },
}}
/>

ViewportRef [#viewportref]

Control scrolling programmatically via a ref.

```tsx title="Programmatic Scrolling"
import { useRef } from 'react';
import { Viewport, ViewportRef } from 'giggles/ui';

const ref = useRef<ViewportRef>(null);

ref.current?.scrollToItem(5);
ref.current?.scrollBy(3);
ref.current?.scrollToTop();
```

<TypeTable
  type={{
  scrollTo: {
    description: 'Scroll to an absolute row offset',
    type: '(offset: number) => void',
  },
  scrollBy: {
    description: 'Scroll by a relative number of rows',
    type: '(delta: number) => void',
  },
  scrollToTop: {
    description: 'Scroll to the top',
    type: '() => void',
  },
  scrollToBottom: {
    description: 'Scroll to the bottom',
    type: '() => void',
  },
  scrollToItem: {
    description: 'Scroll to make the child at the given index visible',
    type: '(index: number) => void',
  },
  getScrollOffset: {
    description: 'Get the current row offset',
    type: '() => number',
  },
  getContentHeight: {
    description: 'Get the total content height in rows',
    type: '() => number',
  },
  getViewportHeight: {
    description: 'Get the visible viewport height',
    type: '() => number',
  },
}}
/>

Keybindings [#keybindings]

| Key                 | Action                          |
| ------------------- | ------------------------------- |
| `j` / `↓`           | Scroll down one row             |
| `k` / `↑`           | Scroll up one row               |
| `PgDn`              | Scroll down one page            |
| `PgUp`              | Scroll up one page              |
| `g`                 | Jump to top                     |
| `G`                 | Jump to bottom                  |
| `Tab` / `Shift+Tab` | Move to next/previous component |

Examples [#examples]

Mixed content [#mixed-content]

```tsx title="Mixed Content"
<Viewport height={15}>
  <Text bold>Log Output</Text>
  <Text dimColor>─────────</Text>
  {entries.map((entry, i) => (
    <Text key={i} color={entry.level === 'error' ? 'red' : 'yellow'}>
      [{entry.level}] {entry.message}
    </Text>
  ))}
</Viewport>
```


# VirtualList



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Callout } from 'fumadocs-ui/components/callout';
import { Terminal } from '@/components/terminal';
import VirtualListExample from '@/components/examples/ui/virtual-list';

A windowed list that only renders visible items. Use it to efficiently display large datasets without mounting every item in the React tree.

When `maxVisible` is set, only that many items render at a time. The list auto-scrolls to keep `highlightIndex` in view. When `maxVisible` is omitted, all items render with no windowing.

VirtualList is a rendering primitive — it has no focus or keybindings. Parent components handle navigation and pass state down. For an interactive scrollable pane with built-in keybindings, see [Viewport](/ui/viewport).

Two scrolling modes: `highlightIndex` auto-scrolls to keep a highlighted item in view, while `scrollOffset` gives direct control over which item appears at the top of the window. Use one or the other, not both.

```tsx title="Basic Usage"
import { VirtualList } from 'giggles/ui';
import { Text } from 'ink';

function LogViewer({ lines, scrollIndex }: { lines: string[]; scrollIndex: number }) {
  return (
    <VirtualList
      items={lines}
      highlightIndex={scrollIndex}
      maxVisible={20}
      render={({ item, index }) => (
        <Text>
          <Text dimColor>{String(index + 1).padStart(4)} </Text>
          {item}
        </Text>
      )}
    />
  );
}
```

<Terminal>
  <VirtualListExample />
</Terminal>

<Callout>
  When `maxVisible` is not set, VirtualList renders all items without windowing. This is useful as a uniform rendering interface — components can always use VirtualList regardless of list size.
</Callout>

API Reference [#api-reference]

VirtualList [#virtuallist]

<TypeTable
  type={{
  items: {
    description: 'Array of items to render',
    type: 'T[]',
    required: true,
  },
  render: {
    description: 'Render function called for each visible item',
    type: '(props: VirtualListRenderProps<T>) => React.ReactNode',
    required: true,
  },
  highlightIndex: {
    description: 'Index of the currently highlighted item. The list auto-scrolls to keep this index visible. Use this for list selection components.',
    type: 'number',
  },
  scrollOffset: {
    description: 'Direct control over which item appears at the top of the visible window. Use this for viewport-style scrolling.',
    type: 'number',
  },
  gap: {
    description: 'Vertical spacing between items (in lines)',
    type: 'number',
    default: '0',
  },
  maxVisible: {
    description: 'Maximum number of items visible at once. When omitted, all items render.',
    type: 'number',
  },
  paginatorStyle: {
    description: 'Style of the scroll indicator shown when items overflow',
    type: "'dots' | 'arrows' | 'scrollbar' | 'counter' | 'none'",
    default: "'dots'",
  },
}}
/>

VirtualListRenderProps [#virtuallistrenderprops]

<TypeTable
  type={{
  item: {
    description: 'The item being rendered',
    type: 'T',
    required: true,
  },
  index: {
    description: 'The index of this item in the original items array',
    type: 'number',
    required: true,
  },
}}
/>

Examples [#examples]

With scrollbar [#with-scrollbar]

```tsx title="With Scrollbar"
<VirtualList
  items={items}
  highlightIndex={currentIndex}
  maxVisible={10}
  paginatorStyle="scrollbar"
  render={({ item }) => <Text>{item.label}</Text>}
/>
```


# API Reference



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Callout } from 'fumadocs-ui/components/callout';

useFocusScope() [#usefocusscope]

Creates a scope node in the focus tree and returns a reactive handle. Wrap children with `<FocusScope handle={scope}>` so nested hooks know their parent.

```ts title="Type Signature"
function useFocusScope(options?: FocusScopeOptions): FocusScopeHandle
```

FocusScopeOptions [#focusscopeoptions]

<TypeTable
  type={{
  parent: {
    description: 'Explicit parent scope. Use when creating a scope in the same component as its parent, bypassing context. Defaults to the nearest <FocusScope> ancestor.',
    type: 'FocusScopeHandle',
  },
  focusKey: {
    description: 'Key used to address this scope from its parent via focusChild/focusChildShallow. Scoped to the immediate parent — no global namespace.',
    type: 'string',
  },
  keybindings: {
    description: 'Keybindings active while this scope or any descendant has focus. Pass a function to receive navigation helpers. Handlers re-register every render so closures are never stale. To register additional keys on the scope or handle text input, use useKeybindings() alongside this option.',
    type: 'Keybindings | ((helpers: FocusScopeHelpers) => Keybindings)',
  },
}}
/>

FocusScopeHandle [#focusscopehandle]

<TypeTable
  type={{
  id: {
    description: 'Unique identifier for this scope node',
    type: 'string',
    required: true,
  },
  hasFocus: {
    description: 'Whether this scope or any descendant currently has focus',
    type: 'boolean',
    required: true,
  },
  isPassive: {
    description: 'Whether this scope is in passive mode — focus has been yielded to the parent via escape()',
    type: 'boolean',
    required: true,
  },
  next: {
    description: 'Focus the next sibling child, descending to the first leaf automatically.',
    type: '() => void',
    required: true,
  },
  prev: {
    description: 'Focus the previous sibling child, descending to the first leaf automatically.',
    type: '() => void',
    required: true,
  },
  nextShallow: {
    description: 'Focus the next sibling child without descending into its children.',
    type: '() => void',
    required: true,
  },
  prevShallow: {
    description: 'Focus the previous sibling child without descending into its children.',
    type: '() => void',
    required: true,
  },
  escape: {
    description: "Yield focus to this scope's own node, enabling passive mode. Parent keybindings become active.",
    type: '() => void',
    required: true,
  },
  drillIn: {
    description: 'Focus the first child of this scope, clearing passive mode. If the scope has no children yet, the focus is queued — the first child to register claims it automatically.',
    type: '() => void',
    required: true,
  },
  focusChild: {
    description: 'Focus the direct child of this scope with the given focusKey, drilling into its first leaf. If the child is a scope with no children yet, the focus is queued. No-op if the key is not found.',
    type: '(key: string) => void',
    required: true,
  },
  focusChildShallow: {
    description: 'Focus the direct child of this scope with the given focusKey, landing on its scope node without drilling in. No-op if the key is not found.',
    type: '(key: string) => void',
    required: true,
  },
}}
/>

`hasFocus` is how a container knows it's in the active focus path — use it for visual feedback, conditional rendering, or any logic that depends on whether the user's attention is inside this scope. `isPassive` reflects the current navigation mode: when true, this scope has yielded and the parent's bindings are active — surface it so the user knows which level they're navigating.

The navigation methods (`next`, `prev`, `drillIn`, etc.) are stable references, safe to call from event handlers. Call them imperatively, not during render.

FocusScopeHelpers [#focusscopehelpers]

The subset of `FocusScopeHandle` passed as the argument to the `keybindings` factory function.

<TypeTable
  type={{
  next: { description: 'Focus the next sibling child, descending to the first leaf automatically.', type: '() => void', required: true },
  prev: { description: 'Focus the previous sibling child, descending to the first leaf automatically.', type: '() => void', required: true },
  nextShallow: { description: 'Focus the next sibling child without descending into its children.', type: '() => void', required: true },
  prevShallow: { description: 'Focus the previous sibling child without descending into its children.', type: '() => void', required: true },
  escape: { description: "Yield focus to this scope's own node, enabling passive mode. Parent keybindings become active.", type: '() => void', required: true },
  drillIn: { description: 'Focus the first child of this scope, clearing passive mode. Queues focus if the scope has no children yet.', type: '() => void', required: true },
  focusChild: { description: 'Focus the direct child registered with the given focusKey, drilling into its first leaf.', type: '(key: string) => void', required: true },
  focusChildShallow: { description: 'Focus the direct child registered with the given focusKey, landing on its scope node without drilling.', type: '(key: string) => void', required: true },
}}
/>

FocusScope [#focusscope]

Sets the parent scope for all children rendered inside it. Children that call `useFocusNode()` or `useFocusScope()` without an explicit `parent` option register under this scope.

<Callout type="warn">
  Every `useFocusScope()` call must have exactly one corresponding `<FocusScope>` rendered. Omitting it throws a `GigglesError` — without it, children silently register under the wrong parent scope and navigation breaks.
</Callout>

```tsx title="Type Signature"
function FocusScope({ handle, children }: {
  handle: FocusScopeHandle;
  children: React.ReactNode;
}): JSX.Element
```

<TypeTable
  type={{
  handle: {
    description: 'The scope handle returned by useFocusScope()',
    type: 'FocusScopeHandle',
    required: true,
  },
  children: {
    description: 'Child components that will register under this scope',
    type: 'React.ReactNode',
    required: true,
  },
}}
/>

useFocusNode() [#usefocusnode]

Registers a component as a leaf node in the focus tree. Use this when the component itself is the focusable target — a list item, a form field, a button. If the component contains other focusable children, use `useFocusScope` instead.

```ts title="Type Signature"
function useFocusNode(options?: FocusNodeOptions): FocusNodeHandle
```

FocusNodeOptions [#focusnodeoptions]

<TypeTable
  type={{
  parent: {
    description: 'Explicit parent scope. Use when creating a node in the same component as its parent scope, bypassing context. Defaults to the nearest <FocusScope> ancestor.',
    type: 'FocusScopeHandle',
  },
  focusKey: {
    description: 'Key used to address this node from its parent scope via focusChild/focusChildShallow. Scoped to the immediate parent — no global namespace.',
    type: 'string',
  },
}}
/>

FocusNodeHandle [#focusnodehandle]

<TypeTable
  type={{
  id: {
    description: 'Unique identifier for this focus node',
    type: 'string',
    required: true,
  },
  hasFocus: {
    description: 'Whether this node currently has focus',
    type: 'boolean',
    required: true,
  },
}}
/>

The `FocusNodeHandle` type can be imported for typing component props:

```tsx title="Typing Props"
import type { FocusNodeHandle } from 'giggles';

function MyComponent({ focus }: { focus: FocusNodeHandle }) {
  return <Text color={focus.hasFocus ? 'green' : 'white'}>Item</Text>;
}
```


# Examples



import { Terminal } from '@/components/terminal';
import FocusChildExample from '@/components/examples/focus/focus-child';
import ControlledFocusExample from '@/components/examples/focus/controlled-focus';
import FileTreeExample from '@/components/examples/focus/file-tree';

Jumping to a named child [#jumping-to-a-named-child]

Iterating with `next` and `prev` works well when children are ordered, but sometimes you want to jump directly to a specific pane — press `1` for the editor, `2` for the terminal. Give each child a `focusKey` and call `focusChild` from the parent keybindings:

```tsx title="Dashboard with named children"
function Dashboard() {
  const root = useFocusScope({
    keybindings: ({ focusChild }) => ({
      '1': () => focusChild('editor'),
      '2': () => focusChild('terminal'),
      '3': () => focusChild('sidebar'),
    })
  });

  return (
    <FocusScope handle={root}>
      <Editor focusKey="editor" />
      <Terminal focusKey="terminal" />
      <Sidebar focusKey="sidebar" />
    </FocusScope>
  );
}
```

<Terminal>
  <FocusChildExample />
</Terminal>

`focusChild` drills into the first leaf of the target scope — the same behaviour as `next`. Use `focusChildShallow` to land on the scope node without entering it. `focusChild` is also available directly on the handle for imperative use outside of keybindings:

```tsx title="Focus child from an event handler"
const root = useFocusScope();

function handleFileOpen(name: string) {
  openFile(name);
  root.focusChild('preview');
}
```

Nested scopes with shared keys [#nested-scopes-with-shared-keys]

Two panels side by side, each containing a `Select`. `j`/`k` navigate items inside the active panel — but at the root level, `j`/`k` should also switch between panels. Because the inner scope consumes those keys first, the user presses `e` to yield, putting the panel into passive mode so the root's `j`/`k` can take over:

```tsx title="Two panels"
function Panel({ title, items }: { title: string; items: string[] }) {
  const scope = useFocusScope({
    keybindings: ({ escape }) => ({ e: escape })
  });

  return (
    <FocusScope handle={scope}>
      <Box
        borderStyle="round"
        borderColor={scope.isPassive ? 'yellow' : scope.hasFocus ? 'green' : 'grey'}
      >
        <Text>{title}</Text>
        <Select options={items.map(i => ({ label: i, value: i }))} />
      </Box>
    </FocusScope>
  );
}

function App() {
  const root = useFocusScope({
    keybindings: ({ next, prev }) => ({ j: next, k: prev })
  });

  return (
    <FocusScope handle={root}>
      <Panel title="Navigation" items={['Home', 'About', 'Contact']} />
      <Panel title="Tools" items={['Grep', 'Find', 'Awk']} />
    </FocusScope>
  );
}
```

<Terminal>
  <ControlledFocusExample />
</Terminal>

Collapsible file tree [#collapsible-file-tree]

A two-level tree where `j`/`k` move between top-level directories without entering them, and `l`/`enter` open the focused directory and move focus inside. The root uses [`nextShallow`/`prevShallow`](/core/focus#navigation-variants) to land on each directory node without drilling into it. The directory scope registers three bindings with a stable shape: `l` guards against re-entry when already open, `enter` is safe without a guard because `Select` always consumes it, and `h` is a harmless no-op when already closed. [`drillIn`](/core/focus#navigation-variants) is deferred — if the directory's children haven't rendered yet when it fires, the store queues the focus and delivers it as soon as the first child registers:

```tsx title="File tree"
import { FocusScope, useFocusScope, useTheme } from 'giggles';
import { Select } from 'giggles/ui';

function DirItem({ name, files }: { name: string; files: string[] }) {
  const [open, setOpen] = useState(false);
  const { indicator, indicatorOpen } = useTheme();

  const scope = useFocusScope({
    keybindings: ({ drillIn }) => ({
      l:     () => { if (!open) { setOpen(true); drillIn(); } },
      enter: () => { setOpen(true); drillIn(); },
      h:     () => setOpen(false),
    })
  });

  return (
    <FocusScope handle={scope}>
      <Box flexDirection="column">
        <Text color={scope.hasFocus ? 'green' : 'white'}>
          {open ? indicatorOpen : indicator} {name}/
        </Text>
        {open && (
          <Select options={files.map(f => ({ label: f, value: f }))} />
        )}
      </Box>
    </FocusScope>
  );
}

function FileTree() {
  const root = useFocusScope({
    keybindings: ({ nextShallow, prevShallow }) => ({
      j: nextShallow, k: prevShallow
    })
  });

  return (
    <FocusScope handle={root}>
      <DirItem name="src" files={['index.ts', 'utils.ts', 'types.ts']} />
      <DirItem name="tests" files={['unit.test.ts', 'e2e.test.ts']} />
    </FocusScope>
  );
}
```

The directory header's color reflects `scope.hasFocus`, which is true whenever any descendant — including files deep inside — has focus. No separate state needed to track whether the container is active.

<Terminal>
  <FileTreeExample />
</Terminal>


# Overview



import { Callout } from 'fumadocs-ui/components/callout';
import { Terminal } from '@/components/terminal';
import NavigableMenuExample from '@/components/examples/focus/navigable-menu';

Quick start [#quick-start]

```tsx title="Navigable menu"
import { FocusScope, useFocusNode, useFocusScope } from 'giggles';

function Menu() {
  const scope = useFocusScope({
    keybindings: ({ next, prev }) => ({ j: next, k: prev, down: next, up: prev })
  });

  return (
    <FocusScope handle={scope}>
      <MenuItem label="New File" />
      <MenuItem label="Open File" />
      <MenuItem label="Save" />
    </FocusScope>
  );
}

function MenuItem({ label }: { label: string }) {
  const focus = useFocusNode();
  return (
    <Text color={focus.hasFocus ? 'green' : 'white'}>{label}</Text>
  );
}
```

<Terminal>
  <NavigableMenuExample />
</Terminal>

Nodes and scopes [#nodes-and-scopes]

The example uses two hooks. Choosing between them comes down to a single question: does this component *contain* focusable children, or *is* it the focusable target?

A **node** (`useFocusNode`) is a focusable target — a list item, a text field, a button. It can receive focus and respond to keys, but has no children in the focus tree. `MenuItem` above is a node.

A **scope** (`useFocusScope`) is a navigable container. It groups focusable children and controls how focus moves between them. Scopes can nest — that's how complex layouts are built. `Menu` above is a scope.

The `keybindings` option takes a function that receives navigation helpers and returns a map of key names to handlers. Handlers re-register on every render, so closures are never stale. Nodes register their keys with [`useKeybindings`](/core/input#registering-keybindings).

Wrap children in `<FocusScope handle={scope}>` to set the parent context. Any `useFocusNode` or `useFocusScope` call inside it registers as a child of that scope.

<Callout type="warn">
  Every `useFocusScope()` call must have exactly one corresponding `<FocusScope>` rendered. Omitting it throws a `GigglesError` — without it, children register under the wrong parent and navigation breaks.
</Callout>

hasFocus propagates up [#hasfocus-propagates-up]

Focus always lives at a single leaf node, but a scope's `hasFocus` is true whenever *any descendant* currently has focus. This propagates up the tree, so a container can highlight its border while focus is several levels deep inside it — no extra state required:

```tsx
<Box borderColor={scope.hasFocus ? 'green' : 'grey'}>
  <FocusScope handle={scope}>
    {children}
  </FocusScope>
</Box>
```

Navigation variants [#navigation-variants]

`next` and `prev` move focus to the next or previous child, automatically descending into the first leaf so navigation feels natural. Most of the time this is what you want.

But consider a collapsible directory that hasn't rendered its children yet. `next` would stall on it — there's no leaf to land on inside a closed directory. `nextShallow` and `prevShallow` handle this: they land on the scope node itself without entering it, so the user can see the item and choose to open it.

Since `nextShallow` lands *on* a scope without entering it, you need a separate action to go inside — that's `drillIn`. Call it alongside `setOpen(true)` in the same handler and focus moves to the first child as soon as it renders:

```tsx
// Root scope — move between items without entering them
keybindings: ({ nextShallow, prevShallow }) => ({
  j: nextShallow,
  k: prevShallow,
})

// Child scope — enter when the user opens it
keybindings: ({ drillIn }) => ({
  l: () => { setOpen(true); drillIn(); },
})
```

Passive mode [#passive-mode]

By default, the innermost matching binding always wins — so a panel that binds `j`/`k` consumes those keys before the parent ever sees them. That's usually correct. But sometimes the same keys need to mean different things at two levels: `j`/`k` navigate items inside a panel, and also switch between panels at the root.

When that happens, the inner scope needs a way to yield. Calling `escape()` marks it passive — it is skipped during [dispatch](/core/input#how-a-keypress-reaches-its-handler) until focus moves elsewhere, so the parent's `j`/`k` fire instead:

```tsx
// Inner scope — yield on 'e'
keybindings: ({ escape }) => ({ e: escape })

// Outer scope — j/k now reach here while inner is passive
keybindings: ({ next, prev }) => ({ j: next, k: prev })
```

`isPassive` lets you reflect the yielded state visually — a yellow border instead of green while the parent is in control. Passive mode clears automatically when focus moves to a different scope:

```tsx
<Box borderColor={scope.isPassive ? 'yellow' : scope.hasFocus ? 'green' : 'grey'}>
```

Addressing children by name [#addressing-children-by-name]

`next` and `prev` iterate in order. When you want to jump directly to a specific child — pressing `1` to open the editor, `2` for the terminal — give that child a `focusKey` and call `focusChild` from the parent:

```tsx
// Parent scope
keybindings: ({ focusChild }) => ({
  '1': () => focusChild('editor'),
  '2': () => focusChild('terminal'),
  '3': () => focusChild('sidebar'),
})

// Children
<Editor focusKey="editor" />
<Terminal focusKey="terminal" />
<Sidebar focusKey="sidebar" />
```

`focusChild` drills into the first leaf of the target — the same behaviour as `next`. Use `focusChildShallow` to land on the scope node without entering it. `focusKey` works on both `useFocusScope` and `useFocusNode` — any focusable child can be addressed by name.

Keys are scoped to the immediate parent, so the same key string can be reused inside sibling scopes without conflict. `focusChild` is also available directly on the handle for imperative use outside of keybindings:

```tsx
function handleFileOpen(name: string) {
  openFile(name);
  root.focusChild('preview');
}
```

***

* [API Reference](/core/focus/api-reference) — full type signatures for `useFocusScope`, `FocusScope`, and `useFocusNode`
* [Examples](/core/focus/examples) — complete worked examples for common focus patterns


# API Reference



import { TypeTable } from 'fumadocs-ui/components/type-table';

useKeybindings() [#usekeybindings]

Registers keybindings that only fire when the component is in the active focus path.

```ts title="Type Signature"
function useKeybindings(
  focus: { id: string },
  bindings: Keybindings,
  options?: KeybindingOptions
): void
```

<TypeTable
  type={{
  focus: {
    description: 'Focus handle from useFocusNode() or useFocusScope()',
    type: '{ id: string }',
    required: true,
  },
  bindings: {
    description: 'Map of key names to handler functions or named binding objects',
    type: 'Keybindings',
    required: true,
  },
  options: {
    description: 'Fallback and bubble configuration for text input scenarios',
    type: 'KeybindingOptions',
  },
}}
/>

KeyHandler [#keyhandler]

```ts title="Type Signature"
type KeyHandler = (input: string, key: Key) => void
```

<TypeTable
  type={{
  input: {
    description: 'The character string for the key pressed',
    type: 'string',
    required: true,
  },
  key: {
    description: 'Ink Key object with boolean properties (downArrow, return, escape, etc.)',
    type: 'Key',
    required: true,
  },
}}
/>

Keybindings [#keybindings]

Each value can be a plain handler function or a named binding object. Named bindings are registered in the command registry and become discoverable via `useKeybindingRegistry`.

<TypeTable
  type={{
  '[key: string]': {
    description: 'Key name mapped to a handler or named binding object. See Key Names below for valid key strings.',
    type: 'KeyHandler | { action: KeyHandler; name: string }',
  },
}}
/>

Key Names [#key-names]

| Key string                    | Triggers on             |
| ----------------------------- | ----------------------- |
| `up`, `down`, `left`, `right` | Arrow keys              |
| `enter`                       | Return / Enter          |
| `escape`                      | Escape                  |
| `tab`                         | Tab                     |
| `shift+tab`                   | Shift + Tab             |
| `backspace`                   | Backspace or Delete (⌫) |
| `delete`                      | Forward delete (⌦)      |
| `pageup`, `pagedown`          | Page Up / Page Down     |
| `home`, `end`                 | Home / End              |
| `ctrl+c`, `ctrl+q`, …         | Ctrl + any letter       |
| `a`, `j`, `?`, …              | Any printable character |

KeybindingOptions [#keybindingoptions]

<TypeTable
  type={{
  fallback: {
    description: 'Handler for keystrokes that don\'t match named bindings. When provided, unmatched keys are routed here instead of bubbling to parent components.',
    type: '(input: string, key: Key) => void',
  },
  bubble: {
    description: 'Key names that skip the fallback and bubble to parent components instead. Use for keys like escape and enter that should always reach parent scopes.',
    type: 'string[]',
  },
}}
/>

When both `fallback` and named bindings are registered, dispatch follows this priority order:

| Priority                 | What happens                   |
| ------------------------ | ------------------------------ |
| 1. Named binding matches | Handler fires, key stops       |
| 2. Key is in `bubble`    | Key propagates to parent scope |
| 3. `fallback` exists     | Fallback handler fires         |
| 4. Nothing matched       | Key propagates to parent scope |

useKeybindingRegistry() [#usekeybindingregistry]

Reads named bindings registered across the app, filtered by scope. Returns bindings in three views depending on how broadly you want to look.

```ts title="Type Signature"
function useKeybindingRegistry(): KeybindingRegistry
```

<TypeTable
  type={{
  all: {
    description: 'All named bindings registered across the entire app',
    type: 'RegisteredKeybinding[]',
    required: true,
  },
  available: {
    description: 'Named bindings currently reachable from the active focus path and its ancestors',
    type: 'RegisteredKeybinding[]',
    required: true,
  },
  local: {
    description: 'Named bindings registered by the component that called useKeybindingRegistry. Empty if no focus handle provided.',
    type: 'RegisteredKeybinding[]',
    required: true,
  },
}}
/>

RegisteredKeybinding [#registeredkeybinding]

<TypeTable
  type={{
  nodeId: {
    description: 'Focus node ID of the registering component',
    type: 'string',
    required: true,
  },
  key: {
    description: 'The key name the binding is registered under',
    type: 'string',
    required: true,
  },
  handler: {
    description: 'The handler function',
    type: 'KeyHandler',
    required: true,
  },
  name: {
    description: 'Human-readable label (only present on named bindings)',
    type: 'string | undefined',
  },
}}
/>

FocusTrap [#focustrap]

Confines all keyboard input to its subtree. When mounted, keys no longer bubble past it — nothing outside the trap receives input. When unmounted, focus returns to the previously focused component.

```tsx title="Type Signature"
function FocusTrap({ children }: {
  children: React.ReactNode;
}): JSX.Element
```

<TypeTable
  type={{
  children: {
    description: 'Components that should receive input exclusively while the trap is mounted',
    type: 'React.ReactNode',
    required: true,
  },
}}
/>


# Examples



import { Terminal } from '@/components/terminal';
import FileListExample from '@/components/examples/input/file-list';
import FocusTrapExample from '@/components/examples/input/focus-trap';

File manager with search [#file-manager-with-search]

A filterable file list composed from `Select` and `TextInput`. Because each component owns its keybindings, the parent scope has no navigation or character-capture logic — it only routes focus between fields. `/` bubbles up from the `Select` (which doesn't consume it) and triggers `focusChild('search')`; `escape` from the `TextInput` (which ignores it) triggers the reverse:

```tsx title="File manager"
function FileManager() {
  const [query, setQuery] = useState('');

  const options = FILES.filter(
    f => !query || f.value.toLowerCase().includes(query.toLowerCase())
  );

  const scope = useFocusScope({
    keybindings: ({ focusChild, next, prev }) => ({
      '/': () => focusChild('search'),
      escape: () => { setQuery(''); focusChild('list'); },
      tab: next,
      'shift+tab': prev,
    }),
  });

  return (
    <Box flexDirection="column" gap={1}>
      <FocusScope handle={scope}>
        <TextInput
          focusKey="search"
          label="/"
          value={query}
          onChange={setQuery}
          onSubmit={() => scope.focusChild('list')}
          placeholder="filter files…"
        />
        <Select focusKey="list" options={options} onSubmit={open} />
      </FocusScope>
    </Box>
  );
}
```

<Terminal>
  <FileListExample />
</Terminal>

Modal with focus trap [#modal-with-focus-trap]

A confirmation dialog that completely blocks input to the menu behind it. Without `FocusTrap`, `j`/`k` on the menu scope would still fire while the dialog is open — the trap prevents that by stopping all key bubbling at the modal boundary:

```tsx title="Modal with FocusTrap"
function ConfirmDialog({ message, onConfirm, onCancel }) {
  const scope = useFocusScope({
    keybindings: ({ next, prev }) => ({
      left: prev,
      right: next,
      escape: onCancel,
    })
  });

  return (
    <Box flexDirection="column" borderStyle="double">
      <Text bold color="yellow">Confirm Action</Text>
      <Text>{message}</Text>
      <FocusScope handle={scope}>
        <MenuItem label="Confirm" onSelect={onConfirm} />
        <MenuItem label="Cancel" onSelect={onCancel} />
      </FocusScope>
    </Box>
  );
}

function App() {
  const [showModal, setShowModal] = useState(false);
  const menuScope = useFocusScope({
    keybindings: ({ next, prev }) => ({ j: next, k: prev })
  });

  return (
    <Box flexDirection="column">
      <FocusScope handle={menuScope}>
        <MenuItem label="New File" onSelect={() => setShowModal(true)} />
        <MenuItem label="Delete" onSelect={() => setShowModal(true)} />
      </FocusScope>

      {showModal && (
        <FocusTrap>
          <ConfirmDialog
            message="Are you sure?"
            onConfirm={() => setShowModal(false)}
            onCancel={() => setShowModal(false)}
          />
        </FocusTrap>
      )}
    </Box>
  );
}
```

<Terminal>
  <FocusTrapExample />
</Terminal>


# Overview



Quick start [#quick-start]

```tsx title="File list navigation"
import { useFocusNode, useKeybindings } from 'giggles';

function FileList() {
  const focus = useFocusNode();
  const [selected, setSelected] = useState(0);
  const files = ['index.ts', 'utils.ts', 'types.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'}>{file}</Text>
      ))}
    </Box>
  );
}
```

How a keypress reaches its handler [#how-a-keypress-reaches-its-handler]

When a key is pressed, giggles walks up the [focus tree](/core/focus) from the currently focused component toward the root, checking each node for a matching handler. The first match wins; unmatched keys keep moving up. Components outside the focused path never receive input.

This is what makes bindings local: the same key can be bound differently at every nesting level, and only the focused path's bindings are consulted. Register app-wide shortcuts on the outermost scope — they fire whenever nothing deeper claims the key first.

Registering keybindings [#registering-keybindings]

`useKeybindings` takes a focus handle as its first argument — bindings only fire when that component is in the active focus path. It works with any focus handle: nodes from `useFocusNode`, or scopes from `useFocusScope`.

For **scopes**, there's an alternative: the `keybindings` option on `useFocusScope` itself. The difference is that the option gives you the [navigation helpers](/core/focus#navigation-variants) — `next`, `prev`, `drillIn`, and friends — which aren't available through `useKeybindings`. Use the option when you need to navigate between children; use `useKeybindings` for everything else: action bindings, `fallback`, `bubble`, or adding bindings to a scope that already has navigation set up.

```tsx
useKeybindings(focus, {
  j: moveDown,
  k: moveUp,
  enter: select,
});
```

You can call `useKeybindings` multiple times in the same component. Bindings from all calls are merged; later calls override earlier ones for duplicate keys. This lets you split navigation and mode-specific bindings into separate calls, which makes conditional spreading cleaner:

```tsx
useKeybindings(focus, {
  ...(!editing && { j: moveDown, k: moveUp }),
  escape: exitMode,
});

useKeybindings(focus, editing ? { enter: confirmEdit } : {});
```

Text input and the fallback [#text-input-and-the-fallback]

Named bindings work well for discrete actions, but they can't capture arbitrary typed characters. For that, use the `fallback` option — a handler that receives any keystroke that doesn't match a named binding:

```tsx
useKeybindings(focus, { escape: exitSearch }, {
  fallback: (input, key) => {
    if (key.backspace) setQuery(q => q.slice(0, -1));
    else if (input) setQuery(q => q + input);
  }
});
```

Some keys should always reach their named binding even when a fallback is active. Use `bubble` to let specific keys skip the fallback and propagate normally:

```tsx
useKeybindings(focus, { escape: exitSearch }, {
  fallback: handleInput,
  bubble: ['escape', 'enter'],
});
```

Named bindings always take priority over the fallback across all `useKeybindings` calls on the same component. If a named binding and the fallback need to compete for the same key at different times, disable the binding conditionally: `...(!searchMode && { j: moveDown })`.

Named bindings and the registry [#named-bindings-and-the-registry]

Bindings can carry a human-readable name, making them discoverable for help screens, command palettes, and key hint bars:

```tsx
useKeybindings(focus, {
  j: { action: moveDown, name: 'Move down' },
  k: { action: moveUp, name: 'Move up' },
  '/': { action: openSearch, name: 'Search' },
});
```

`useKeybindingRegistry` reads all named bindings filtered by the current focus path:

```tsx
function HelpScreen() {
  const registry = useKeybindingRegistry();

  return (
    <Box flexDirection="column">
      {registry.available.map((cmd) => (
        <Box key={`${cmd.nodeId}-${cmd.key}`} gap={2}>
          <Text color="cyan">{cmd.key}</Text>
          <Text>{cmd.name}</Text>
        </Box>
      ))}
    </Box>
  );
}
```

`available` returns only the bindings reachable from the current focus path — so the help screen always reflects what's actually active, not everything registered across the entire app.

Trapping focus [#trapping-focus]

Key bubbling normally walks all the way to the root. For modal dialogs and confirmation prompts, you may want to cut that path entirely — nothing outside the modal should receive input until it's dismissed. `FocusTrap` does this: mount it and all input is confined to its subtree. Unmount it and focus returns to where it was before.

```tsx
function App() {
  const [showModal, setShowModal] = useState(false);

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

* [API Reference](/core/input/api-reference) — full type signatures for `useKeybindings`, `useKeybindingRegistry`, and `FocusTrap`
* [Examples](/core/input/examples) — complete worked examples for common input patterns


# API Reference



import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Callout } from 'fumadocs-ui/components/callout';

Router [#router]

Manages a stack of screens. Only the top screen is visible; others remain mounted but hidden.

<TypeTable
  type={{
  initialScreen: {
    description: 'Name of the screen to display first. Must match a Screen child.',
    type: 'string',
    required: true,
  },
  initialParams: {
    description: 'Params to pass to the initial screen',
    type: 'Record<string, unknown>',
  },
  restoreFocus: {
    description: 'Restore the previously focused element when returning to a screen. When false, always focuses the first child.',
    type: 'boolean',
    default: 'true',
  },
  children: {
    description: 'Screen components defining available routes',
    type: 'React.ReactNode',
    required: true,
  },
}}
/>

<Callout type="warn">
  Throws a `GigglesError` if `initialScreen` does not match any registered Screen name.
</Callout>

Screen [#screen]

Declarative route definition. Renders nothing — used by Router to register screens.

<TypeTable
  type={{
  name: {
    description: 'Unique name for this screen',
    type: 'string',
    required: true,
  },
  component: {
    description: 'Component to render when this screen is active',
    type: 'React.ComponentType',
    required: true,
  },
}}
/>

useNavigation() [#usenavigation]

Returns navigation methods and current route state. Must be used within a Router.

```ts title="Type Signature"
function useNavigation(): NavigationContextValue
```

<TypeTable
  type={{
  currentRoute: {
    description: 'The current screen route (name, params, id)',
    type: 'ScreenRoute',
    required: true,
  },
  active: {
    description: 'Whether this screen is the top of the stack',
    type: 'boolean',
    required: true,
  },
  canGoBack: {
    description: 'Whether the stack has more than one screen',
    type: 'boolean',
    required: true,
  },
  push: {
    description: 'Push a new screen onto the stack',
    type: '(name: string, params?: Record<string, unknown>) => void',
    required: true,
  },
  pop: {
    description: 'Remove the top screen from the stack. No-op if only one screen remains.',
    type: '() => void',
    required: true,
  },
  replace: {
    description: 'Replace the top screen with a new one',
    type: '(name: string, params?: Record<string, unknown>) => void',
    required: true,
  },
  reset: {
    description: 'Clear the stack and set a single screen',
    type: '(name: string, params?: Record<string, unknown>) => void',
    required: true,
  },
}}
/>

<Callout type="warn">
  `push`, `replace`, and `reset` throw a `GigglesError` if the screen name is not registered.
</Callout>

ScreenRoute [#screenroute]

<TypeTable
  type={{
  id: {
    description: 'Unique identifier for this stack entry',
    type: 'number',
    required: true,
  },
  name: {
    description: 'The screen name as registered with Screen',
    type: 'string',
    required: true,
  },
  params: {
    description: 'Params passed when the screen was pushed',
    type: 'Record<string, unknown>',
  },
}}
/>


# Examples



import { Terminal } from '@/components/terminal';
import NestedRouterExample from '@/components/examples/router/nested-router';

Nested routers [#nested-routers]

Each `Router` manages its own independent stack, so you can nest them for tabbed layouts or sub-navigation. The outer router handles top-level navigation; inner routers handle navigation within a screen:

```tsx title="Nested routers"
function App() {
  return (
    <GigglesProvider>
      <Router initialScreen="tabs">
        <Screen name="tabs" component={Tabs} />
        <Screen name="detail" component={Detail} />
      </Router>
    </GigglesProvider>
  );
}

function Tabs() {
  return (
    <Router initialScreen="tab1">
      <Screen name="tab1" component={Tab1} />
      <Screen name="tab2" component={Tab2} />
    </Router>
  );
}
```

<Terminal>
  <NestedRouterExample />
</Terminal>


# Overview



import { Terminal } from '@/components/terminal';
import BasicRouterExample from '@/components/examples/router/basic-router';

Quick start [#quick-start]

```tsx title="Basic router"
import { GigglesProvider, Router, Screen, useNavigation, useFocusNode, useKeybindings } from 'giggles';

function App() {
  return (
    <GigglesProvider>
      <Router initialScreen="home">
        <Screen name="home" component={Home} />
        <Screen name="settings" component={Settings} />
      </Router>
    </GigglesProvider>
  );
}

function Home() {
  const { push } = useNavigation();
  const focus = useFocusNode();

  useKeybindings(focus, {
    s: () => push('settings'),
  });

  return <Text>Home <Text dimColor>Press s for settings</Text></Text>;
}

function Settings() {
  const { pop, canGoBack } = useNavigation();
  const focus = useFocusNode();

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

  return <Text>Settings {canGoBack && <Text dimColor>Press q to go back</Text>}</Text>;
}
```

<Terminal>
  <BasicRouterExample />
</Terminal>

How the stack works [#how-the-stack-works]

`Router` maintains a stack of screens. Only the top screen is visible — but every screen below it stays mounted, preserving its state. Navigating back is instant: there's no re-initialization, no lost scroll position, no refetched data.

The four stack operations map directly to what you'd expect:

* `push(name, params)` — add a screen on top
* `pop()` — remove the top screen, return to the previous one
* `replace(name, params)` — swap the current screen without adding to the stack
* `reset(name, params)` — clear the stack and start fresh from a single screen

Call these from `useNavigation()` inside any screen component.

Focus integration [#focus-integration]

When a screen becomes the top of the stack, its first focusable child receives focus automatically. When navigating back, focus is restored to whichever element was focused before the screen was covered — so the user's position is preserved across navigation.

To always focus the first child on return instead, set `restoreFocus={false}` on the `Router`.

***

* [API Reference](/core/router/api-reference) — full type signatures for `Router`, `Screen`, and `useNavigation`
* [Examples](/core/router/examples) — nested routers and tabbed layouts