enuno/ink

Ink

Ink is a framework for building command-line interfaces using React components. It provides the same component-based UI building experience that React offers in the browser, but for command-line apps. The framework leverages Yoga, a Flexbox layout engine, enabling developers to use familiar CSS-like properties in terminal environments.

When to Use

• Building interactive CLI applications with React
• Creating terminal UIs with complex layouts
• Building progress indicators and spinners for CLI tools
• Creating multi-step wizards in the terminal
• Building dev tools with rich terminal output
• Creating dashboard-style CLI interfaces
• Handling keyboard input in terminal apps
• Building accessible CLI applications with screen reader support
• Testing terminal UI components

Adoption

Ink is used by major projects including:

• Shopify CLI
• Gatsby
• Prisma
• Google's Gemini CLI
• Cloudflare Wrangler
• Parcel

---

Installation

npm install ink react

For TypeScript:

npm install ink react
npm install -D @types/react

Quick Start with Template

npx create-ink-app my-ink-cli
cd my-ink-cli
npm start

---

Basic Usage

import React from 'react';
import {render, Text} from 'ink';

const App = () => <Text color="green">Hello, Ink!</Text>;

render(<App />);

Counter Example

import React, {useState, useEffect} from 'react';
import {render, Text} from 'ink';

const Counter = () => {
  const [counter, setCounter] = useState(0);

  useEffect(() => {
    const timer = setInterval(() => {
      setCounter(c => c + 1);
    }, 100);
    return () => clearInterval(timer);
  }, []);

  return <Text color="green">{counter} tests passed</Text>;
};

render(<Counter />);

---

Core Components

Text

The <Text> component handles all text rendering. Text content must be wrapped in this component.

import {Text} from 'ink';

// Basic text
<Text>Hello World</Text>

// With colors
<Text color="green">Success</Text>
<Text color="#ff0000">Error (hex)</Text>
<Text color="rgb(255, 128, 0)">Warning (rgb)</Text>

// With styles
<Text bold>Bold text</Text>
<Text italic>Italic text</Text>
<Text underline>Underlined</Text>
<Text strikethrough>Strikethrough</Text>
<Text inverse>Inverted colors</Text>
<Text dimColor>Dimmed text</Text>

// Combined styles
<Text bold color="cyan" backgroundColor="blue">
  Styled text
</Text>

Text Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | color | string | - | Text color (named, hex, rgb) | | backgroundColor | string | - | Background color | | dimColor | boolean | false | Dim the color | | bold | boolean | false | Bold text | | italic | boolean | false | Italic text | | underline | boolean | false | Underlined text | | strikethrough | boolean | false | Strikethrough text | | inverse | boolean | false | Swap foreground/background | | wrap | string | "wrap" | Text wrapping mode |

Wrap modes:

• wrap - Wrap text (default)
• truncate / truncate-end - Truncate at end with ellipsis
• truncate-start - Truncate at start
• truncate-middle - Truncate in middle

---

Box

<Box> is the primary layout component - a flexbox container for organizing UI elements.

import {Box, Text} from 'ink';

// Basic layout
<Box>
  <Text>Left</Text>
  <Text>Right</Text>
</Box>

// Column layout
<Box flexDirection="column">
  <Text>Top</Text>
  <Text>Bottom</Text>
</Box>

// With padding and margin
<Box padding={2} margin={1}>
  <Text>Padded content</Text>
</Box>

// With border
<Box borderStyle="round" borderColor="green" padding={1}>
  <Text>Bordered box</Text>
</Box>

// Centered content
<Box justifyContent="center" alignItems="center" height={10}>
  <Text>Centered</Text>
</Box>

Box Props - Dimensions

| Prop | Type | Description | |------|------|-------------| | width | number | string | Width in spaces or percentage | | height | number | string | Height in lines or percentage | | minWidth | number | Minimum width | | minHeight | number | Minimum height |

Box Props - Padding

| Prop | Type | Description | |------|------|-------------| | padding | number | All sides | | paddingX | number | Left and right | | paddingY | number | Top and bottom | | paddingTop | number | Top only | | paddingBottom | number | Bottom only | | paddingLeft | number | Left only | | paddingRight | number | Right only |

Box Props - Margin

| Prop | Type | Description | |------|------|-------------| | margin | number | All sides | | marginX | number | Left and right | | marginY | number | Top and bottom | | marginTop | number | Top only | | marginBottom | number | Bottom only | | marginLeft | number | Left only | | marginRight | number | Right only |

Box Props - Flexbox

| Prop | Type | Default | Description | |------|------|---------|-------------| | flexDirection | string | "row" | row, row-reverse, column, column-reverse | | flexGrow | number | 0 | Grow factor | | flexShrink | number | 1 | Shrink factor | | flexBasis | number | string | - | Initial size | | flexWrap | string | "nowrap" | nowrap, wrap, wrap-reverse | | alignItems | string | - | flex-start, center, flex-end | | alignSelf | string | - | auto, flex-start, center, flex-end | | justifyContent | string | - | flex-start, center, flex-end, space-between, space-around, space-evenly | | gap | number | - | Gap between children | | columnGap | number | - | Horizontal gap | | rowGap | number | - | Vertical gap |

Box Props - Borders

| Prop | Type | Description | |------|------|-------------| | borderStyle | string | object | Border style | | borderColor | string | Border color | | borderTop | boolean | Show top border | | borderBottom | boolean | Show bottom border | | borderLeft | boolean | Show left border | | borderRight | boolean | Show right border |

Border styles:

• single - Single line (─│)
• double - Double line (═║)
• round - Rounded corners (╭╮╰╯)
• bold - Bold line (━┃)
• singleDouble - Single horizontal, double vertical
• doubleSingle - Double horizontal, single vertical
• classic - ASCII (+, -, |)

Box Props - Other

| Prop | Type | Default | Description | |------|------|---------|-------------| | display | string | "flex" | flex or none | | overflow | string | "visible" | visible or hidden | | overflowX | string | - | Horizontal overflow | | overflowY | string | - | Vertical overflow | | backgroundColor | string | - | Background color |

---

Newline

Insert line breaks within text.

import {Text, Newline} from 'ink';

<Text>
  First line
  <Newline />
  Second line
  <Newline count={2} />
  After two newlines
</Text>

---

Spacer

Flexible space that expands along the flex direction.

import {Box, Text, Spacer} from 'ink';

// Push items apart
<Box>
  <Text>Left</Text>
  <Spacer />
  <Text>Right</Text>
</Box>

// Equivalent to flexGrow: 1
<Box>
  <Text>Left</Text>
  <Box flexGrow={1} />
  <Text>Right</Text>
</Box>

---

Static

Render output once without updates. Perfect for logs or completed tasks.

import {Static, Box, Text} from 'ink';

const App = ({tests}) => (
  <>
    <Static items={tests}>
      {test => (
        <Box key={test.id}>
          <Text color="green">✔ {test.title}</Text>
        </Box>
      )}
    </Static>

    <Box marginTop={1}>
      <Text>Running more tests...</Text>
    </Box>
  </>
);

Props:

• items - Array of items to render
• children - Function (item, index) => ReactNode

Only new items trigger renders; previously rendered items are not updated.

---

Transform

Modify text output before rendering.

import {Transform, Text} from 'ink';

// Uppercase transform
<Transform transform={output => output.toUpperCase()}>
  <Text>hello world</Text>
</Transform>
// Output: HELLO WORLD

// Per-line transform (hanging indent)
<Transform transform={(line, index) =>
  index === 0 ? line : `  ${line}`
}>
  <Text>First line{'\n'}Second line{'\n'}Third line</Text>
</Transform>

---

Hooks

useInput

Capture keyboard input.

import {useInput, useApp} from 'ink';

const App = () => {
  const {exit} = useApp();

  useInput((input, key) => {
    // Character input
    if (input === 'q') {
      exit();
    }

    // Arrow keys
    if (key.upArrow) {
      // Move up
    }
    if (key.downArrow) {
      // Move down
    }

    // Modifiers
    if (key.ctrl && input === 'c') {
      exit();
    }

    // Special keys
    if (key.return) {
      // Enter pressed
    }
    if (key.escape) {
      // Escape pressed
    }
  });

  return <Text>Press 'q' to quit</Text>;
};

Key object properties: | Property | Description | |----------|-------------| | upArrow | Up arrow pressed | | downArrow | Down arrow pressed | | leftArrow | Left arrow pressed | | rightArrow | Right arrow pressed | | return | Enter key pressed | | escape | Escape key pressed | | ctrl | Ctrl modifier held | | shift | Shift modifier held | | meta | Meta/Cmd modifier held | | tab | Tab key pressed | | backspace | Backspace pressed | | delete | Delete pressed | | pageUp | Page Up pressed | | pageDown | Page Down pressed |

Options:

// Disable input handling conditionally
useInput(handler, {isActive: false});

---

useApp

Access app-level methods.

import {useApp} from 'ink';

const App = () => {
  const {exit} = useApp();

  const handleDone = () => {
    exit(); // Exit successfully
  };

  const handleError = () => {
    exit(new Error('Something went wrong')); // Exit with error
  };

  return <Text>App running...</Text>;
};

---

useStdin

Access stdin stream and raw mode.

import {useStdin} from 'ink';

const App = () => {
  const {stdin, isRawModeSupported, setRawMode} = useStdin();

  useEffect(() => {
    if (isRawModeSupported) {
      setRawMode(true);
    }
    return () => setRawMode(false);
  }, []);

  return <Text>Raw mode: {isRawModeSupported ? 'enabled' : 'not supported'}</Text>;
};

---

useStdout / useStderr

Access output streams.

import {useStdout, useStderr} from 'ink';

const App = () => {
  const {stdout, write} = useStdout();
  const {stderr, write: writeError} = useStderr();

  const logToStdout = () => {
    write('Direct stdout output\n');
  };

  const logToStderr = () => {
    writeError('Error output\n');
  };

  return <Text>Stream access available</Text>;
};

---

useFocus

Enable focus on components for Tab navigation.

import {useFocus, Box, Text} from 'ink';

const FocusableItem = ({label}) => {
  const {isFocused} = useFocus();

  return (
    <Box>
      <Text color={isFocused ? 'green' : 'gray'}>
        {isFocused ? '>' : ' '} {label}
      </Text>
    </Box>
  );
};

const App = () => (
  <Box flexDirection="column">
    <FocusableItem label="Option 1" />
    <FocusableItem label="Option 2" />
    <FocusableItem label="Option 3" />
  </Box>
);

Options:

useFocus({
  autoFocus: true,    // Focus on mount
  isActive: true,     // Enable/disable focus
  id: 'my-component'  // Unique identifier for programmatic focus
});

---

useFocusManager

Control focus programmatically.

import {useFocusManager, useInput} from 'ink';

const App = () => {
  const {
    enableFocus,
    disableFocus,
    focusNext,
    focusPrevious,
    focus
  } = useFocusManager();

  useInput((input, key) => {
    if (key.tab) {
      if (key.shift) {
        focusPrevious();
      } else {
        focusNext();
      }
    }
  });

  return (
    <Box flexDirection="column">
      <FocusableItem id="item-1" />
      <FocusableItem id="item-2" />
    </Box>
  );
};

---

render() API

import {render} from 'ink';

const {rerender, unmount, waitUntilExit, clear} = render(<App />, options);

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | stdout | stream | process.stdout | Output stream | | stdin | stream | process.stdin | Input stream | | stderr | stream | process.stderr | Error stream | | exitOnCtrlC | boolean | true | Exit on Ctrl+C | | patchConsole | boolean | true | Intercept console output | | debug | boolean | false | Debug mode (no clear) | | maxFps | number | 30 | Maximum frame rate | | incrementalRendering | boolean | false | Only update changed lines |

Instance Methods

// Re-render with new props
rerender(<App newProp={value} />);

// Unmount and exit
unmount();

// Wait for exit (returns promise)
await waitUntilExit();

// Clear rendered output
clear();

---

Testing

Use ink-testing-library for testing Ink components.

npm install --save-dev ink-testing-library

import {render} from 'ink-testing-library';
import App from './App';

test('renders greeting', () => {
  const {lastFrame} = render(<App name="World" />);
  expect(lastFrame()).toContain('Hello, World');
});

test('updates on input', () => {
  const {lastFrame, stdin} = render(<Counter />);

  expect(lastFrame()).toContain('Count: 0');

  stdin.write('i'); // Increment
  expect(lastFrame()).toContain('Count: 1');
});

Testing API

| Method | Description | |--------|-------------| | lastFrame() | Get last rendered output as string | | frames | Array of all rendered frames | | stdin | Writable stream for simulating input | | rerender(element) | Re-render with new element | | unmount() | Unmount the component |

---

Accessibility

Ink supports ARIA attributes for screen reader compatibility.

<Box
  aria-role="list"
  aria-label="Menu options"
>
  <Box aria-role="listitem">
    <Text>Option 1</Text>
  </Box>
  <Box aria-role="listitem">
    <Text>Option 2</Text>
  </Box>
</Box>

ARIA Props

| Prop | Type | Description | |------|------|-------------| | aria-label | string | Accessible label | | aria-hidden | boolean | Hide from screen readers | | aria-role | string | ARIA role | | aria-state | object | State properties |

Supported roles:

• button, checkbox, radio, radiogroup
• list, listitem
• menu, menuitem
• progressbar
• tab, tablist
• timer, toolbar, table

Screen Reader Detection

import {useIsScreenReaderEnabled} from 'ink';

const App = () => {
  const isScreenReaderEnabled = useIsScreenReaderEnabled();

  return (
    <Box aria-label="Main content">
      {isScreenReaderEnabled ? (
        <Text>Screen reader friendly content</Text>
      ) : (
        <Text>Visual content with colors</Text>
      )}
    </Box>
  );
};

---

Common Patterns

Loading Spinner

import React, {useState, useEffect} from 'react';
import {Text} from 'ink';

const Spinner = () => {
  const [frame, setFrame] = useState(0);
  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];

  useEffect(() => {
    const timer = setInterval(() => {
      setFrame(f => (f + 1) % frames.length);
    }, 80);
    return () => clearInterval(timer);
  }, []);

  return <Text color="cyan">{frames[frame]} Loading...</Text>;
};

Progress Bar

import {Box, Text} from 'ink';

const ProgressBar = ({percent}) => {
  const width = 20;
  const filled = Math.round(width * percent / 100);
  const empty = width - filled;

  return (
    <Box>
      <Text color="green">{'█'.repeat(filled)}</Text>
      <Text color="gray">{'░'.repeat(empty)}</Text>
      <Text> {percent}%</Text>
    </Box>
  );
};

Menu Selection

import React, {useState} from 'react';
import {Box, Text, useInput} from 'ink';

const Menu = ({items, onSelect}) => {
  const [selected, setSelected] = useState(0);

  useInput((input, key) => {
    if (key.upArrow) {
      setSelected(s => Math.max(0, s - 1));
    }
    if (key.downArrow) {
      setSelected(s => Math.min(items.length - 1, s + 1));
    }
    if (key.return) {
      onSelect(items[selected]);
    }
  });

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

Two-Column Layout

import {Box, Text} from 'ink';

const TwoColumn = () => (
  <Box>
    <Box width="50%" borderStyle="single" padding={1}>
      <Text>Left Column</Text>
    </Box>
    <Box width="50%" borderStyle="single" padding={1}>
      <Text>Right Column</Text>
    </Box>
  </Box>
);

---

Resources

• Repository: https://github.com/vadimdemedes/ink
• NPM: https://www.npmjs.com/package/ink
• Testing Library: https://github.com/vadimdemedes/ink-testing-library
• Awesome Ink: https://github.com/vadimdemedes/awesome-ink
• License: MIT

---

Related Packages

| Package | Description | |---------|-------------| | ink-spinner | Spinner component | | ink-text-input | Text input component | | ink-select-input | Select/menu component | | ink-table | Table component | | ink-link | Clickable links | | ink-gradient | Gradient text | | ink-big-text | Large ASCII text | | ink-testing-library | Testing utilities |