ink-scrollable-list

A scrollable list component for Ink with keyboard navigation, customizable styling, and scroll bars.

Features

• 📜 Smooth scrolling - Navigate line-by-line or jump by pages through long lists
• ⌨️ Custom key mappings - Configure any keys for navigation, including special keys
• 🎨 Customizable styling - Configure borders, colors, and scroll bar appearance
• 📏 Flexible scroll bar - Position on left or right, customize character and style
• 🎯 Type-safe - Built with TypeScript

Installation

npm install ink-scrollable-list

Or with other package managers:

yarn add ink-scrollable-list ink react
bun add ink-scrollable-list ink react

Usage

Basic Example

import React from "react";
import { render } from "ink";
import { ScrollableList } from "ink-scrollable-list";

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

const App = () => {
  return <ScrollableList items={items} visibleCount={10} />;
};

render(<App />);

Default Controls: ↑/k (up), ↓/j (down), PageUp, PageDown

Note: The list must be focused to respond to keyboard input. Use Tab to cycle focus. Border color changes when focused (blue by default).

Custom Objects

Items need an id property or toString() method:

const items = [
  { id: 1, name: "Task 1", toString: () => "✓ Task 1" },
  { id: 2, name: "Task 2", toString: () => "✗ Task 2" },
];

<ScrollableList items={items} visibleCount={5} />;

If your items don't have an id property, use keyFn to specify which property to use as the unique key:

interface Task {
  timestamp: number;
  name: string;
  toString(): string;
}

<ScrollableList
  items={tasks}
  keyFn={(task) => task.timestamp}
  visibleCount={10}
/>;

Custom Rendering

Use renderItem for custom item layouts:

<ScrollableList
  items={events}
  renderItem={(event, index) => (
    <Box gap={1}>
      <Text dimColor>{new Date(event.timestamp).toLocaleTimeString()}</Text>
      <Text bold>[{event.type.toUpperCase()}]</Text>
      <Text>{event.message}</Text>
    </Box>
  )}
/>

Handling Long Text Content

When displaying long text content, you may need to truncate items to prevent horizontal overflow, especially when the scrollbar is present. Use the useListItemWidth hook to calculate the safe width for text content:

import { ScrollableList, useListItemWidth } from "ink-scrollable-list";

const MyList = () => {
  const safeWidth = useListItemWidth(true, "round"); // with scrollbar, round border

  return (
    <ScrollableList
      items={longItems}
      showScrollBar={true}
      borderStyle="round"
      renderItem={(item, index) => (
        <Text>
          {item.text.length > safeWidth
            ? `${item.text.slice(0, safeWidth - 3)}...`
            : item.text}
        </Text>
      )}
    />
  );
};

The hook accounts for borders, scrollbar space, and padding to provide the maximum safe width for text content.

Starting at the Bottom

Use startAtBottom to show the last items first (useful for logs or chat):

<ScrollableList items={logMessages} visibleCount={10} startAtBottom={true} />

API

| Prop | Type | Default | Description | | -------------------- | --------------------------------------- | ------------ | ----------------------------------------------------- | | items | T[] | Required | Array of items to display | | visibleCount | number | 10 | Number of items visible at once | | startAtBottom | boolean | false | Start with the last items visible (bottom of list) | | renderItem | (item: T, index: number) => ReactNode | - | Custom render function for each item | | keyFn | (item: T) => string \| number | - | Function to extract unique key from item | | showScrollBar | boolean | true | Whether to show the scroll bar | | scrollBarPosition | 'left' \| 'right' | 'right' | Position of the scroll bar | | scrollBarChar | string | '█' | Character used for the scroll bar indicator | | scrollBarStyle | object | - | { color?: string, backgroundColor?: string } | | borderStyle | BorderStyle | 'round' | Border style ('single', 'double', 'round', etc) | | borderColor | string | 'white' | Border color when not focused | | focusedBorderColor | string | 'blue' | Border color when focused | | keyMap | object | - | Custom key mappings (see below) |

Hooks

useListItemWidth

Hook to calculate the safe width for text content, accounting for scrollbar and border space:

const safeWidth = useListItemWidth(showScrollBar, borderStyle);

Parameters:

• showScrollBar (boolean, default: true) - Whether the scrollbar is visible
• borderStyle (string, optional) - The border style being used

Returns: Number representing the safe character width for text content.

keyMap

Customize keyboard controls:

{
  up?: string[];       // default: ['up', 'k']
  down?: string[];     // default: ['down', 'j']
  pageUp?: string[];   // default: ['pageup']
  pageDown?: string[]; // default: ['pagedown']
}

Example:

<ScrollableList
  items={items}
  keyMap={{
    up: ["w", "up"],
    down: ["s", "down"],
  }}
/>

Supported keys: Single characters (e.g., 'j', 'w'), 'up', 'down', 'left', 'right', 'pageup', 'pagedown', 'home', 'end', 'return'/'enter', 'escape'/'esc', 'space', 'tab', 'backspace', 'delete'

ScrollableItem Type

Items must have a toString() method. Optionally include an id property or use keyFn:

interface ScrollableItem {
  id?: string | number;
  toString(): string;
}

Requirements

• React >= 18.0.0
• Ink >= 6.0.0

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or create an Issue.