ink-scrollable-box

Scrollable container component for Ink with keyboard navigation, vim bindings, scrollbar styles, and auto-follow.

Install

npm install ink-scrollable-box
yarn add ink-scrollable-box
pnpm add ink-scrollable-box

Requires ink >= 4 and react >= 18 as peer dependencies.

Quick Start

import {render} from 'ink';
import {ScrollableBox} from 'ink-scrollable-box';

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

render(<ScrollableBox height={15} lines={lines} autoFocus border />);

Features

Two content modes: lines (string array, virtualized) and children (React nodes)
Keyboard navigation with arrow keys, Page Up/Down, Home/End
Vim bindings (j/k/g/G/u/d, Ctrl+U/D)
Auto-follow output (log tailing) with manual scroll-to-pause
Proportional scrollbar with 4 built-in styles (block, line, thick, dots)
Half-line precision scrollbar rendering for block style
Tab-based focus management across multiple panes
autoFocus for immediate keyboard control on mount
Controlled mode via offset / onOffsetChange
Ref API for programmatic scrolling (scrollTo, scrollToIndex, etc.)
Linked scroll via useLinkedScroll hook
Infinite scroll callbacks (onReachEnd, onReachStart)
Variable-height child measurement (measureChildren)
Overscan for pre-rendering items above/below viewport
Fully customizable scrollbar characters, colors, and border styling
Standalone useScrollable and useScrollableInput hooks
Zero runtime dependencies (peer deps only)
TypeScript-first with full type exports

Examples

Lines Mode (basic)

import {render, Box, Text} from 'ink';
import {ScrollableBox} from 'ink-scrollable-box';

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

render(
  <Box flexDirection="column">
    <Text bold>100 items -- j/k/g/G to navigate</Text>
    <ScrollableBox height={15} lines={lines} autoFocus border />
  </Box>
);

Children Mode (styled React nodes)

import {render, Text} from 'ink';
import {ScrollableBox} from 'ink-scrollable-box';

const items = [
  {color: 'green', text: 'Build succeeded'},
  {color: 'red', text: 'Test: auth.test.ts failed'},
  {color: 'yellow', text: 'Coverage: 89%'},
];

render(
  <ScrollableBox height={6} autoFocus border>
    {items.map((item, i) => (
      <Text key={i} color={item.color}>{item.text}</Text>
    ))}
  </ScrollableBox>
);

Log Follower (followOutput)

import {useState, useEffect} from 'react';
import {render, Text} from 'ink';
import {ScrollableBox} from 'ink-scrollable-box';

function App() {
  const [logs, setLogs] = useState<string[]>([]);
  useEffect(() => {
    const id = setInterval(() => {
      setLogs(prev => [...prev, `[${new Date().toISOString()}] Entry #${prev.length + 1}`]);
    }, 200);
    return () => clearInterval(id);
  }, []);

  return <ScrollableBox height={15} lines={logs} followOutput autoFocus border />;
}

render(<App />);

Multi-Pane (Tab focus)

import {render, Box, Text} from 'ink';
import {ScrollableBox} from 'ink-scrollable-box';

const left = Array.from({length: 30}, (_, i) => `Left-${i + 1}`);
const right = Array.from({length: 50}, (_, i) => `Right-${i + 1}`);

render(
  <Box flexDirection="row" gap={2}>
    <ScrollableBox height={10} lines={left} border id="left" autoFocus />
    <ScrollableBox height={10} lines={right} border id="right" />
  </Box>
);

Controlled Mode

import {useState} from 'react';
import {render} from 'ink';
import {ScrollableBox} from 'ink-scrollable-box';

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

function App() {
  const [offset, setOffset] = useState(0);
  return <ScrollableBox height={10} lines={lines} offset={offset} onOffsetChange={setOffset} autoFocus />;
}

render(<App />);

Ref API (programmatic scrolling)

import {useRef} from 'react';
import {render, Box, Text} from 'ink';
import {ScrollableBox, ScrollableBoxRef} from 'ink-scrollable-box';

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

function App() {
  const ref = useRef<ScrollableBoxRef>(null);
  // Call ref.current.scrollToIndex(50, {align: 'center'}) to jump to item 50
  return <ScrollableBox ref={ref} height={10} lines={lines} autoFocus border />;
}

render(<App />);

Linked Scroll (useLinkedScroll)

Synchronize scroll position across multiple panes:

import {render, Box} from 'ink';
import {ScrollableBox, useLinkedScroll} from 'ink-scrollable-box';

const left = Array.from({length: 100}, (_, i) => `Left-${i + 1}`);
const right = Array.from({length: 100}, (_, i) => `Right-${i + 1}`);

function App() {
  const linked = useLinkedScroll();
  return (
    <Box flexDirection="row" gap={2}>
      <ScrollableBox height={10} lines={left} offset={linked.offset} onOffsetChange={linked.onOffsetChange} autoFocus border />
      <ScrollableBox height={10} lines={right} offset={linked.offset} onOffsetChange={linked.onOffsetChange} border />
    </Box>
  );
}

render(<App />);

Infinite Scroll (onReachEnd)

import {useState, useCallback} from 'react';
import {render} from 'ink';
import {ScrollableBox} from 'ink-scrollable-box';

function App() {
  const [lines, setLines] = useState(Array.from({length: 50}, (_, i) => `Item ${i + 1}`));
  const loadMore = useCallback(() => {
    setLines(prev => [...prev, ...Array.from({length: 20}, (_, i) => `Item ${prev.length + i + 1}`)]);
  }, []);

  return <ScrollableBox height={15} lines={lines} onReachEnd={loadMore} reachThreshold={5} autoFocus border />;
}

render(<App />);

API Reference

`<ScrollableBox />`

Core Props

Prop	Type	Default	Description
`height`	`number`	required	Viewport height in terminal lines
`width`	`number`	--	Viewport width in terminal columns. When set, fixes the container width.
`lines`	`string[]`	--	String content (mutually exclusive with `children`)
`children`	`ReactNode`	--	React node content (mutually exclusive with `lines`)
`followOutput`	`boolean`	`false`	Auto-scroll to bottom when content grows
`scrollStep`	`number`	`1`	Lines per arrow key / j/k press
`border`	`boolean`	`false`	Render a rounded border around the viewport
`overscan`	`number`	`0`	Extra items to pre-render above/below viewport
`measureChildren`	`boolean`	`false`	Measure actual heights of multi-line children (O(n) render)
`debug`	`boolean`	`false`	Disable overflow clipping for layout debugging

Scrollbar Props

Prop	Type	Default	Description
`showScrollbar`	`boolean`	`true`	Show the proportional scrollbar
`scrollbarPosition`	`'inside' \| 'outside'`	`'inside'`	`inside` renders the scrollbar alongside content within the border; `outside` renders it to the right of the border, saving 1 column of content width
`showIndicators`	`boolean`	`true`	Show overflow indicators above/below content
`scrollbarStyle`	`'block' \| 'line' \| 'thick' \| 'dots'`	`'block'`	Built-in scrollbar visual style
`scrollbarCharacter`	`string`	per style	Override the scrollbar thumb character
`trackCharacter`	`string`	per style	Override the scrollbar track character
`upIndicator`	`string`	`▲`	Top overflow indicator character
`downIndicator`	`string`	`▼`	Bottom overflow indicator character
`scrollbarColor`	`string`	--	Thumb color when focused
`scrollbarDimColor`	`string`	--	Thumb color when unfocused
`trackColor`	`string`	--	Track color

Focus and Keyboard Props

Prop	Type	Default	Description
`focusable`	`boolean`	`true`	Participate in Tab focus cycle
`autoFocus`	`boolean`	`false`	Auto-focus on mount
`id`	`string`	--	Focus ID for programmatic focus / multi-pane
`enableVimBindings`	`boolean`	`true`	Enable vim-style keys (j/k/g/G/u/d)

Border Styling Props

Prop	Type	Default	Description
`borderColor`	`string`	`'blue'`	Border color when focused
`borderDimColor`	`string`	`'gray'`	Border color when unfocused

Callback Props

Prop	Type	Default	Description
`onScroll`	`(state: ScrollState) => void`	--	Called on every scroll position change
`onFocus`	`() => void`	--	Called when the component gains focus
`onBlur`	`() => void`	--	Called when the component loses focus
`onContentHeightChange`	`(height: number, previousHeight: number) => void`	--	Called when total content height changes
`onViewportSizeChange`	`(height: number, previousHeight: number) => void`	--	Called when viewport height changes
`onItemHeightChange`	`(index: number, height: number, previousHeight: number) => void`	--	Called when a measured child's height changes (requires `measureChildren`)
`onReachEnd`	`() => void`	--	Called when scroll is within `reachThreshold` of the bottom
`onReachStart`	`() => void`	--	Called when scroll is within `reachThreshold` of the top
`reachThreshold`	`number`	`5`	Lines from edge to trigger `onReachEnd` / `onReachStart`

Controlled Mode Props

Prop	Type	Default	Description
`offset`	`number`	--	Controlled scroll offset (makes the component controlled)
`onOffsetChange`	`(offset: number) => void`	--	Called when offset changes in controlled mode

`useScrollable(options)`

Standalone scroll state hook. Use this to build a fully custom scroll UI.

Options:

Option	Type	Default	Description
`contentHeight`	`number`	required	Total number of content rows
`viewportHeight`	`number`	required	Visible row count
`scrollStep`	`number`	`1`	Rows per scroll action
`followOutput`	`boolean`	`false`	Auto-scroll when content grows
`initialOffset`	`number`	`0`	Starting scroll position
`controlledOffset`	`number`	--	External controlled offset (overrides internal state)
`onOffsetChange`	`(offset: number) => void`	--	Called when offset would change (for controlled mode)

Returns (UseScrollableResult = ScrollState & ScrollActions):

Field	Type	Description
`offset`	`number`	Current scroll offset (first visible row index)
`contentHeight`	`number`	Total content rows
`viewportHeight`	`number`	Visible rows
`canScrollUp`	`boolean`	True when not at top
`canScrollDown`	`boolean`	True when not at bottom
`isAtTop`	`boolean`	True when at first row
`isAtBottom`	`boolean`	True when at last row
`percentage`	`number`	Scroll position 0--100
`scrollUp()`	`() => void`	Scroll up by `scrollStep`
`scrollDown()`	`() => void`	Scroll down by `scrollStep`
`scrollTo(n)`	`(n: number) => void`	Jump to absolute offset
`scrollToTop()`	`() => void`	Jump to top
`scrollToBottom()`	`() => void`	Jump to bottom
`pageUp()`	`() => void`	Scroll up one full page
`pageDown()`	`() => void`	Scroll down one full page
`halfPageUp()`	`() => void`	Scroll up half a page
`halfPageDown()`	`() => void`	Scroll down half a page

`useScrollableInput(options)`

Wires Ink's useInput to a UseScrollableResult. Used internally by ScrollableBox but exported for custom UIs.

Options:

Option	Type	Default	Description
`scroll`	`UseScrollableResult`	required	The scroll state object from `useScrollable`
`focusable`	`boolean`	`true`	Participate in Tab focus cycle
`autoFocus`	`boolean`	`false`	Auto-focus on mount
`id`	`string`	--	Focus ID for programmatic focus
`enableVimBindings`	`boolean`	`true`	Enable vim-style keys

Returns:

Field	Type	Description
`isFocused`	`boolean`	Whether the component currently has focus

`useLinkedScroll(options?)`

Synchronize scroll position across multiple ScrollableBox instances.

Options:

Option	Type	Default	Description
`initialOffset`	`number`	`0`	Starting offset

Returns:

Field	Type	Description
`offset`	`number`	Shared scroll offset
`onOffsetChange`	`(offset: number) => void`	Spread onto each `ScrollableBox`

`<Scrollbar />`

Standalone scrollbar component. Used internally but exported for custom layouts.

Prop	Type	Default	Description
`offset`	`number`	required	Current scroll offset
`contentHeight`	`number`	required	Total content rows
`viewportHeight`	`number`	required	Visible rows
`isFocused`	`boolean`	required	Whether the parent is focused (affects color)
`scrollbarStyle`	`'block' \| 'line' \| 'thick' \| 'dots'`	`'block'`	Built-in visual style
`thumbCharacter`	`string`	per style	Override thumb character
`trackCharacter`	`string`	per style	Override track character
`thumbColor`	`string`	--	Thumb color when focused
`thumbDimColor`	`string`	--	Thumb color when unfocused
`trackColor`	`string`	--	Track color

`ScrollableBoxRef`

All methods available on a ref obtained via useRef<ScrollableBoxRef>().

Method	Description
`scrollTo(offset)`	Jump to a specific offset (clamped to valid range)
`scrollBy(delta)`	Scroll by a relative delta (positive = down, negative = up)
`scrollToTop()`	Jump to the top
`scrollToBottom()`	Jump to the bottom
`scrollUp()`	Scroll up by `scrollStep` lines
`scrollDown()`	Scroll down by `scrollStep` lines
`pageUp()`	Scroll up by one viewport height
`pageDown()`	Scroll down by one viewport height
`halfPageUp()`	Scroll up by half viewport height
`halfPageDown()`	Scroll down by half viewport height
`scrollToIndex(index, options?)`	Scroll to a specific item index with optional `{align: 'start' \| 'center' \| 'end' \| 'auto'}`
`getScrollState()`	Returns the current `ScrollState` object
`getBottomOffset()`	Returns the maximum scroll offset (`contentHeight - viewportHeight`)
`getItemHeight(index)`	Get the height of a child in terminal lines (returns 1 in non-measure mode)
`getItemPosition(index)`	Get `{top, height}` of a child, or `undefined` if out of range
`remeasureItem(index)`	Force re-measurement of a child (requires `measureChildren`)

Keyboard Shortcuts

Key	Action
Up / k	Scroll up
Down / j	Scroll down
g	Jump to top
G (Shift+G)	Jump to bottom
Page Up / u	Scroll up one page
Page Down / d	Scroll down one page
Ctrl+U	Scroll up half page
Ctrl+D	Scroll down half page
Home	Jump to top
End	Jump to bottom
Tab	Move focus to next pane

Vim bindings (j, k, g, G, u, d) can be disabled with enableVimBindings={false}. Arrow keys, Page Up/Down, Home/End, and Ctrl+U/D are always active when focused.

Scrollbar Styles

Set scrollbarStyle to change the built-in look:

Style	Thumb	Track
`block` (default)	`█`	`░`
`line`	`│`	(space)
`thick`	`┃`	`╏`
`dots`	`●`	`·`

The block style uses half-line precision rendering (▀/▄ characters) for smoother positioning. Override individual characters with scrollbarCharacter and trackCharacter.

How It Works

Lines mode slices the content array to render only visible rows (lines.slice(offset, offset + height)). Render cost is O(viewport) regardless of content size -- 100,000 lines renders the same as 100.

Children mode renders only the visible subset of React children. When measureChildren is enabled, all children are rendered and measured for accurate scroll math with multi-line content (O(n) rendering).

The useScrollable hook manages offset state and exposes scroll actions. useScrollableInput wires Ink's useInput to those actions. ScrollableBox composes both internally.

Comparison with Alternatives

Feature	ink-scrollable-box	ink-scroll-view	ink-scrollbar
Keyboard navigation	vim + arrows + Page + Home/End	--	--
Focus management	Tab cycling + autoFocus	--	--
followOutput	yes	--	--
Dual content modes	lines + children	children only	N/A
Scrollbar styles	4 built-in + custom	--	partial
Controlled mode	yes	--	--
Linked scroll	useLinkedScroll hook	--	--
Infinite scroll	onReachEnd / onReachStart	--	--
Standalone hooks	useScrollable, useScrollableInput	--	--
Ref API	scrollToIndex, getItemHeight, etc.	--	--
TypeScript	first-class	yes	yes
Dependencies	0 (peer only)	0 (peer only)	0

Contributing

See CONTRIBUTING.md.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.github/workflows		.github/workflows
docs		docs
examples		examples
media		media
src		src
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts
xo.config.js		xo.config.js

Folders and files

Latest commit

History

Repository files navigation

ink-scrollable-box

Install

Quick Start

Features

Examples

Lines Mode (basic)

Children Mode (styled React nodes)

Log Follower (followOutput)

Multi-Pane (Tab focus)

Controlled Mode

Ref API (programmatic scrolling)

Linked Scroll (useLinkedScroll)

Infinite Scroll (onReachEnd)

API Reference

<ScrollableBox />

Core Props

Scrollbar Props

Focus and Keyboard Props

Border Styling Props

Callback Props

Controlled Mode Props

useScrollable(options)

useScrollableInput(options)

useLinkedScroll(options?)

<Scrollbar />

ScrollableBoxRef

Keyboard Shortcuts

Scrollbar Styles

How It Works

Comparison with Alternatives

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`<ScrollableBox />`

`useScrollable(options)`

`useScrollableInput(options)`

`useLinkedScroll(options?)`

`<Scrollbar />`

`ScrollableBoxRef`

Packages