React component library for Ink CLIs

Repository · Documentation

Features

• 28 ready-made components, pre-styled and ready to drop in:
  • Inputs — TextInput, EmailInput (domain completion), PasswordInput (masked), ConfirmInput
  • Lists — UnorderedList, OrderedList (both nestable), Table
  • Selection & navigation — Select, MultiSelect, Tabs, Stepper, Switch, Toggle, SelectableRow
  • Status & feedback — Spinner, ProgressBar, SkeletonBar, SkeletonRows, StatusMessage, Alert, Badge, Toast
  • Layout & chrome — Banner, Header, Panel (bordered pane, optional focus state), Columns, FooterHints, KeyValue, LoadingScreen, ScrollView
• Behaviour hooks — useTabs and useListCursor own the keyboard state that every consumer used to hand-roll, so Tab/Shift+Tab and arrow/vim navigation behave the same everywhere
• Full @inkjs/ui parity — every upstream component has an equivalent, plus a dozen more the design system adds on top
• Colourblind-safe by design — state is signalled by shape, case, and glyph, never colour alone
• Design tokens included — established palettes (colors, softColors, tonalColors), spacing, and reusable semantic symbols, ASCII fallbacks, border presets, and motion tokens
• Full TypeScript support — ships compiled output with .d.ts declarations for every component and token type
• ESM only, zero config — no runtime bundling step; just import and render
• Peer-dependency light — only requires ink ≥ 7 and react ≥ 19

Install

npm install @rigerc/ink-ui

Until this fork is published under the @rigerc npm scope, you can install directly from its GitHub branch:

npm install github:rigerc/ink-ui#chore/rebrand-rigerc-scope

Git installs build dist/ automatically using the package's prepare script. After publication, use the scoped npm install command above.

ink and react are peer dependencies and must be installed separately:

npm install ink react

Ink compatibility

@rigerc/ink-ui supports Ink 7 and Ink 8 on Node.js 22 or later. Ink 8 requires React 19.3 or later; when installing Ink 8, install a matching version of React:

npm install ink@^8 react@^19.3.0

The library preserves the same public component API across both Ink majors.

Building with an AI agent

The package ships AGENTS.md, a short brief covering the composition rules and house conventions that the type definitions cannot express — which components own the keyboard, what to compose for a given screen, and the traps. Point your agent at it:

node_modules/@rigerc/ink-ui/AGENTS.md

Host appearance options

SelectableRow, FooterHints, ConfirmInput, Spinner and StatusMessage accept local appearance overrides. Omit a color to keep the house default, or pass null for terminal-default foreground. Glyph choices and reduced motion remain independent. See widget appearance for a terminal-native/ASCII example and keyboard ownership notes.

Usage

import React from 'react';
import {render} from 'ink';
import {Banner, Header, Badge, Spinner, colors} from '@rigerc/ink-ui';

const App = () => (
  <>
    <Banner title="my-tool" subtitle="v1.0.0" />
    <Header subtitle="Synchronising files…">Status</Header>
    <Badge variant="success">done</Badge>
    <Spinner label="Loading…" />
  </>
);

render(<App />);

Inputs report their value through onChange/onSubmit, and lists nest with a shape-distinct marker per level:

import {Text} from 'ink';
import {EmailInput, PasswordInput, UnorderedList} from '@rigerc/ink-ui';

const SignUp = () => (
  <>
    <EmailInput placeholder="[email protected]" onSubmit={setEmail} />
    <PasswordInput placeholder="Password" onSubmit={setPassword} />
    <UnorderedList>
      <UnorderedList.Item>
        <Text>Choose a plan</Text>
        <UnorderedList>
          <UnorderedList.Item>
            <Text>Free</Text>
          </UnorderedList.Item>
          <UnorderedList.Item>
            <Text>Pro</Text>
          </UnorderedList.Item>
        </UnorderedList>
      </UnorderedList.Item>
    </UnorderedList>
  </>
);

Components stay presentational and controlled — they take active/value and render. The behaviour hooks supply the keyboard state to drive them, so the two compose without either forcing the other:

import {Tabs, useTabs, useListCursor} from '@rigerc/ink-ui';

const items = [
  {value: 'open', label: 'Open', count: 3},
  {value: 'done', label: 'Done'},
];

const Inbox = ({rows}) => {
  const {active} = useTabs(items); // Tab or → forward, Shift+Tab or ← back, wraps
  const {cursor} = useListCursor(rows.length); // ↑/↓ and k/j, clamps at the ends
  return <Tabs active={active} items={items} />;
};

Both take { isActive } so a screen with several focus regions can gate them, and useListCursor takes { wrap } for genuinely circular lists. useTabs wraps by default because a tab bar is a ring; useListCursor clamps because a list has ends.

All components accept only the props they need — no theme provider or context required. Design tokens are plain objects:

import {colors, spacing} from '@rigerc/ink-ui';

// colors.accent   → "#FF8C00"
// colors.success  → "#5FD7A7"
// spacing.md      → 3

Development

git clone https://github.com/rigerc/ink-ui.git
cd ink-ui
npm install
npm run dev

Formatting

Code formatting uses Oxfmt with the same single-quote and object-brace-spacing rules as ink-cli-starter. Run the formatter before committing changes:

npm run format        # Format files in place
npm run format:check  # Report files requiring formatting (no changes written)

CI checks formatting for changed TypeScript and JavaScript files in src/, scripts/, and tools/. Existing untouched files are exempt until a one-time formatting pass is committed. npm run format:check still checks the whole repository locally and may report legacy files that need formatting.

Interactive gallery

Run npm run demo to browse live component previews. Use ↑/↓ or j/k to select an entry, Enter to focus an interactive example, and Esc to return to the gallery. The Stepper preview demonstrates async canProceed validation, back/cancel, completion, restart, ASCII progress and vertical progress (space marks details ready, b goes back, a changes glyphs, v changes layout, and r restarts). The Design tokens preview shows shared colors, Unicode/ASCII symbols, borders, spacing and spinner frames; press a while focused to switch the glyph set.

npm run build compiles TypeScript to dist/. npm run dev runs the compiler in watch mode.

📚 Full documentation → ink-ui/docs

Design-only screen skill

For screen planning and UX reviews, see the Ink UI Screen Design skill. It provides component selection guidance, Page and responsive layout patterns, keyboard/focus conventions, semantic visual tokens, screen-state design, and a critique checklist. It is a documentation-only skill; using it does not change the library's runtime behavior.