ink-virtual-list 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 archcorsair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# ink-virtual-list
+
+A virtualized list component for [Ink](https://github.com/vadimdemedes/ink) terminal applications. Only renders visible items for optimal performance with large datasets.
+
+## Features
+
+- **Virtualized rendering** - Only renders items visible in the viewport
+- **Automatic scrolling** - Keeps selected item in view as you navigate
+- **Terminal-aware** - Responds to terminal resize events
+- **Flexible height** - Fixed height or auto-fill available terminal space
+- **Customizable indicators** - Override default overflow indicators ("▲ N more")
+- **TypeScript first** - Full type safety with generics
+- **Imperative API** - Programmatic scrolling via ref
+
+## Installation
+
+```bash
+# npm
+npm install ink-virtual-list
+
+# jsr
+npx jsr add @archcorsair/ink-virtual-list
+
+# bun
+bun add ink-virtual-list
+```
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { VirtualList } from 'ink-virtual-list';
+import { Text } from 'ink';
+import { useState } from 'react';
+
+function App() {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const items = Array.from({ length: 1000 }, (_, i) => `Item ${i + 1}`);
+
+  return (
+    <VirtualList
+      items={items}
+      selectedIndex={selectedIndex}
+      height={10}
+      renderItem={({ item, isSelected }) => (
+        <Text color={isSelected ? 'cyan' : 'white'}>
+          {isSelected ? '> ' : '  '}
+          {item}
+        </Text>
+      )}
+    />
+  );
+}
+```
+
+### Auto-fill Terminal Height
+
+```tsx
+<VirtualList
+  items={items}
+  height="auto"
+  reservedLines={5}  // Reserve space for header/footer
+  renderItem={({ item }) => <Text>{item}</Text>}
+/>
+```
+
+### Custom Overflow Indicators
+
+```tsx
+<VirtualList
+  items={items}
+  renderOverflowTop={(count) => <Text dimColor>↑ {count} hidden</Text>}
+  renderOverflowBottom={(count) => <Text dimColor>↓ {count} hidden</Text>}
+  renderItem={({ item }) => <Text>{item}</Text>}
+/>
+```
+
+### Imperative Scrolling
+
+```tsx
+import { useRef } from 'react';
+import type { VirtualListRef } from 'ink-virtual-list';
+
+function App() {
+  const listRef = useRef<VirtualListRef>(null);
+
+  const scrollToTop = () => {
+    listRef.current?.scrollToIndex(0, 'top');
+  };
+
+  return (
+    <VirtualList
+      ref={listRef}
+      items={items}
+      renderItem={({ item }) => <Text>{item}</Text>}
+    />
+  );
+}
+```
+
+## API
+
+### Props
+
+#### Required
+
+- **`items: T[]`** - Array of items to render
+- **`renderItem: (props: RenderItemProps<T>) => ReactNode`** - Render function for each visible item
+  - Receives: `{ item: T, index: number, isSelected: boolean }`
+
+#### Optional
+
+- **`selectedIndex?: number`** - Index of currently selected item (default: `0`)
+- **`keyExtractor?: (item: T, index: number) => string`** - Custom key extractor for list items
+- **`height?: number | "auto"`** - Fixed height in lines or `"auto"` to fill terminal (default: `10`)
+- **`reservedLines?: number`** - Lines to reserve when using `height="auto"` (default: `0`)
+- **`itemHeight?: number`** - Height of each item in lines (default: `1`)
+- **`showOverflowIndicators?: boolean`** - Show "N more" indicators (default: `true`)
+- **`renderOverflowTop?: (count: number) => ReactNode`** - Custom top overflow indicator
+- **`renderOverflowBottom?: (count: number) => ReactNode`** - Custom bottom overflow indicator
+- **`renderScrollBar?: (viewport: ViewportState) => ReactNode`** - Custom scrollbar renderer
+- **`onViewportChange?: (viewport: ViewportState) => void`** - Callback when viewport changes
+
+### Ref Methods
+
+```typescript
+interface VirtualListRef {
+  scrollToIndex: (index: number, alignment?: 'auto' | 'top' | 'center' | 'bottom') => void;
+  getViewport: () => ViewportState;
+  remeasure: () => void;
+}
+```
+
+- **`scrollToIndex(index, alignment?)`** - Scroll to bring an index into view
+  - `'auto'` (default) - Only scroll if needed
+  - `'top'` - Align item to top of viewport
+  - `'center'` - Center item in viewport
+  - `'bottom'` - Align item to bottom of viewport
+- **`getViewport()`** - Get current viewport state (`{ offset, visibleCount, totalCount }`)
+- **`remeasure()`** - Force recalculation of viewport dimensions
+
+### Types
+
+```typescript
+interface RenderItemProps<T> {
+  item: T;
+  index: number;
+  isSelected: boolean;
+}
+
+interface ViewportState {
+  offset: number;       // Items scrolled past
+  visibleCount: number; // Items currently visible
+  totalCount: number;   // Total items
+}
+```
+
+## Advanced Example
+
+```tsx
+import { VirtualList } from 'ink-virtual-list';
+import { Box, Text } from 'ink';
+import { useRef, useState } from 'react';
+import type { VirtualListRef } from 'ink-virtual-list';
+
+interface Todo {
+  id: string;
+  title: string;
+  completed: boolean;
+}
+
+function TodoApp() {
+  const [todos] = useState<Todo[]>([
+    { id: '1', title: 'Learn Ink', completed: true },
+    { id: '2', title: 'Build CLI', completed: false },
+    // ... 1000s more
+  ]);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const listRef = useRef<VirtualListRef>(null);
+
+  return (
+    <Box flexDirection="column">
+      <Text bold>My Todos ({todos.length})</Text>
+
+      <VirtualList
+        ref={listRef}
+        items={todos}
+        selectedIndex={selectedIndex}
+        height="auto"
+        reservedLines={3}
+        keyExtractor={(todo) => todo.id}
+        renderItem={({ item, isSelected }) => (
+          <Box>
+            <Text color={isSelected ? 'cyan' : 'white'}>
+              {isSelected ? '❯ ' : '  '}
+              {item.completed ? '✓' : '○'} {item.title}
+            </Text>
+          </Box>
+        )}
+      />
+
+      <Text dimColor>
+        {selectedIndex + 1} / {todos.length}
+      </Text>
+    </Box>
+  );
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+import { ReactNode } from "react";
+/**
+* Props passed to the renderItem function for each visible item.
+*/
+interface RenderItemProps<T> {
+	/** The item data from the items array */
+	item: T;
+	/** The index of this item in the full items array */
+	index: number;
+	/** Whether this item is currently selected */
+	isSelected: boolean;
+}
+/**
+* Represents the current viewport state of the virtual list.
+*/
+interface ViewportState {
+	/** Number of items scrolled past (hidden above viewport) */
+	offset: number;
+	/** Number of items currently visible in the viewport */
+	visibleCount: number;
+	/** Total number of items in the list */
+	totalCount: number;
+}
+/**
+* Props for the VirtualList component.
+*/
+interface VirtualListProps<T> {
+	/** Array of items to render */
+	items: T[];
+	/** Render function for each visible item */
+	renderItem: (props: RenderItemProps<T>) => ReactNode;
+	/** Index of the currently selected item (default: 0) */
+	selectedIndex?: number;
+	/** Function to extract a unique key for each item */
+	keyExtractor?: (item: T, index: number) => string;
+	/** Fixed height in lines, or "auto" to fill available terminal space (default: 10) */
+	height?: number | "auto";
+	/** Lines to reserve when using height="auto" (e.g., for headers/footers) */
+	reservedLines?: number;
+	/** Height of each item in lines (default: 1) */
+	itemHeight?: number;
+	/** Whether to show "N more" indicators when items overflow (default: true) */
+	showOverflowIndicators?: boolean;
+	/** Custom renderer for the top overflow indicator */
+	renderOverflowTop?: (count: number) => ReactNode;
+	/** Custom renderer for the bottom overflow indicator */
+	renderOverflowBottom?: (count: number) => ReactNode;
+	/** Custom renderer for a scrollbar (receives viewport state) */
+	renderScrollBar?: (viewport: ViewportState) => ReactNode;
+	/** Callback fired when the viewport changes */
+	onViewportChange?: (viewport: ViewportState) => void;
+}
+/**
+* Imperative handle methods exposed via ref.
+*/
+interface VirtualListRef {
+	/** Scroll to bring a specific index into view */
+	scrollToIndex: (index: number, alignment?: "auto" | "top" | "center" | "bottom") => void;
+	/** Get the current viewport state */
+	getViewport: () => ViewportState;
+	/** Force recalculation of viewport dimensions */
+	remeasure: () => void;
+}
+/**
+* Represents the terminal dimensions.
+*/
+interface TerminalSize {
+	/** Number of rows (lines) in the terminal */
+	rows: number;
+	/** Number of columns (characters) in the terminal */
+	columns: number;
+}
+/**
+* Hook that returns the current terminal size and updates on resize.
+* Uses Ink's stdout to detect terminal dimensions.
+*/
+declare function useTerminalSize(): TerminalSize;
+declare function VirtualListInner<T>(props: VirtualListProps<T>, ref: React.ForwardedRef<VirtualListRef>): React.JSX.Element;
+declare const VirtualList: <T>(props: VirtualListProps<T> & {
+	ref?: React.ForwardedRef<VirtualListRef>;
+}) => ReturnType<typeof VirtualListInner>;
+export { useTerminalSize, VirtualListRef, VirtualListProps, VirtualList, ViewportState, TerminalSize, RenderItemProps };

package/dist/index.js

@@ -0,0 +1,174 @@
+// src/useTerminalSize.ts
+import { useStdout } from "ink";
+import { useEffect, useState } from "react";
+var DEFAULT_ROWS = 24;
+var DEFAULT_COLUMNS = 80;
+function useTerminalSize() {
+  const { stdout } = useStdout();
+  const [size, setSize] = useState({
+    rows: stdout.rows ?? DEFAULT_ROWS,
+    columns: stdout.columns ?? DEFAULT_COLUMNS
+  });
+  useEffect(() => {
+    const handleResize = () => {
+      setSize({
+        rows: stdout.rows ?? DEFAULT_ROWS,
+        columns: stdout.columns ?? DEFAULT_COLUMNS
+      });
+    };
+    stdout.on("resize", handleResize);
+    return () => {
+      stdout.off("resize", handleResize);
+    };
+  }, [stdout]);
+  return size;
+}
+// src/VirtualList.tsx
+import { Box, Text } from "ink";
+import { forwardRef, useEffect as useEffect2, useImperativeHandle, useMemo, useState as useState2 } from "react";
+import { jsxDEV } from "react/jsx-dev-runtime";
+var DEFAULT_HEIGHT = 10;
+var DEFAULT_ITEM_HEIGHT = 1;
+function calculateViewportOffset(selectedIndex, currentOffset, visibleCount) {
+  if (selectedIndex < currentOffset) {
+    return selectedIndex;
+  }
+  if (selectedIndex >= currentOffset + visibleCount) {
+    return selectedIndex - visibleCount + 1;
+  }
+  return currentOffset;
+}
+function VirtualListInner(props, ref) {
+  const {
+    items,
+    renderItem,
+    selectedIndex = 0,
+    keyExtractor,
+    height = DEFAULT_HEIGHT,
+    reservedLines = 0,
+    itemHeight = DEFAULT_ITEM_HEIGHT,
+    showOverflowIndicators = true,
+    renderOverflowTop,
+    renderOverflowBottom,
+    renderScrollBar,
+    onViewportChange
+  } = props;
+  const { rows: terminalRows } = useTerminalSize();
+  const resolvedHeight = useMemo(() => {
+    if (typeof height === "number") {
+      return height;
+    }
+    return Math.max(1, terminalRows - reservedLines);
+  }, [height, terminalRows, reservedLines]);
+  const resolvedItemHeight = itemHeight ?? DEFAULT_ITEM_HEIGHT;
+  const indicatorLines = showOverflowIndicators ? 2 : 0;
+  const availableHeight = Math.max(0, resolvedHeight - indicatorLines);
+  const visibleCount = Math.floor(availableHeight / resolvedItemHeight);
+  const clampedSelectedIndex = Math.max(0, Math.min(selectedIndex, items.length - 1));
+  const calculatedOffset = useMemo(() => {
+    if (items.length === 0)
+      return 0;
+    const maxOffset = Math.max(0, items.length - visibleCount);
+    let offset = 0;
+    if (clampedSelectedIndex >= visibleCount) {
+      offset = clampedSelectedIndex - visibleCount + 1;
+    }
+    return Math.min(Math.max(0, offset), maxOffset);
+  }, [items.length, visibleCount, clampedSelectedIndex]);
+  const [viewportOffset, setViewportOffset] = useState2(calculatedOffset);
+  useEffect2(() => {
+    const newOffset = calculateViewportOffset(clampedSelectedIndex, viewportOffset, visibleCount);
+    if (newOffset !== viewportOffset) {
+      const maxOffset = Math.max(0, items.length - visibleCount);
+      setViewportOffset(Math.min(newOffset, maxOffset));
+    }
+  }, [clampedSelectedIndex, viewportOffset, visibleCount, items.length]);
+  const viewport = useMemo(() => ({
+    offset: viewportOffset,
+    visibleCount,
+    totalCount: items.length
+  }), [viewportOffset, visibleCount, items.length]);
+  useEffect2(() => {
+    onViewportChange?.(viewport);
+  }, [viewport, onViewportChange]);
+  useImperativeHandle(ref, () => ({
+    scrollToIndex: (index, alignment = "auto") => {
+      const clampedIndex = Math.max(0, Math.min(index, items.length - 1));
+      let newOffset;
+      switch (alignment) {
+        case "top":
+          newOffset = clampedIndex;
+          break;
+        case "center":
+          newOffset = clampedIndex - Math.floor(visibleCount / 2);
+          break;
+        case "bottom":
+          newOffset = clampedIndex - visibleCount + 1;
+          break;
+        default:
+          newOffset = calculateViewportOffset(clampedIndex, viewportOffset, visibleCount);
+      }
+      const maxOffset = Math.max(0, items.length - visibleCount);
+      setViewportOffset(Math.min(Math.max(0, newOffset), maxOffset));
+    },
+    getViewport: () => viewport,
+    remeasure: () => {
+      setViewportOffset((prev) => {
+        const maxOffset = Math.max(0, items.length - visibleCount);
+        return Math.min(prev, maxOffset);
+      });
+    }
+  }), [items.length, visibleCount, viewportOffset, viewport]);
+  const overflowTop = viewportOffset;
+  const overflowBottom = Math.max(0, items.length - viewportOffset - visibleCount);
+  const visibleItems = items.slice(viewportOffset, viewportOffset + visibleCount);
+  const defaultOverflowTop = (count) => /* @__PURE__ */ jsxDEV(Box, {
+    paddingLeft: 2,
+    children: /* @__PURE__ */ jsxDEV(Text, {
+      dimColor: true,
+      children: [
+        "▲ ",
+        count,
+        " more"
+      ]
+    }, undefined, true, undefined, this)
+  }, undefined, false, undefined, this);
+  const defaultOverflowBottom = (count) => /* @__PURE__ */ jsxDEV(Box, {
+    paddingLeft: 2,
+    children: /* @__PURE__ */ jsxDEV(Text, {
+      dimColor: true,
+      children: [
+        "▼ ",
+        count,
+        " more"
+      ]
+    }, undefined, true, undefined, this)
+  }, undefined, false, undefined, this);
+  const topIndicator = renderOverflowTop ?? defaultOverflowTop;
+  const bottomIndicator = renderOverflowBottom ?? defaultOverflowBottom;
+  return /* @__PURE__ */ jsxDEV(Box, {
+    flexDirection: "column",
+    children: [
+      showOverflowIndicators && overflowTop > 0 && topIndicator(overflowTop),
+      visibleItems.map((item, idx) => {
+        const actualIndex = viewportOffset + idx;
+        const key = keyExtractor ? keyExtractor(item, actualIndex) : String(actualIndex);
+        const itemProps = {
+          item,
+          index: actualIndex,
+          isSelected: actualIndex === clampedSelectedIndex
+        };
+        return /* @__PURE__ */ jsxDEV(Box, {
+          children: renderItem(itemProps)
+        }, key, false, undefined, this);
+      }),
+      showOverflowIndicators && overflowBottom > 0 && bottomIndicator(overflowBottom),
+      renderScrollBar?.(viewport)
+    ]
+  }, undefined, true, undefined, this);
+}
+var VirtualList = forwardRef(VirtualListInner);
+export {
+  useTerminalSize,
+  VirtualList
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "ink-virtual-list",
+  "version": "0.1.0",
+  "description": "A virtualized list component for Ink terminal applications",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "bunup",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "prepublishOnly": "bun run build",
+    "publish:npm": "npm publish",
+    "publish:jsr": "bun run build && npx jsr publish",
+    "version:patch": "bun pm version patch",
+    "version:minor": "bun pm version minor",
+    "version:major": "bun pm version major"
+  },
+  "keywords": [
+    "ink",
+    "react",
+    "cli",
+    "terminal",
+    "tui",
+    "virtual-list",
+    "virtualized",
+    "scrolling"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/archcorsair/ink-virtual-list"
+  },
+  "peerDependencies": {
+    "ink": "^6.6.0",
+    "react": "^19.2.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@types/bun": "latest",
+    "@types/react": "^19.2.7",
+    "bunup": "^0.16.17",
+    "typescript": "^5.9.3"
+  }
+}

package/src/VirtualList.tsx

@@ -0,0 +1,192 @@
+import { Box, Text } from "ink";
+import { forwardRef, useEffect, useImperativeHandle, useMemo, useState } from "react";
+import type { RenderItemProps, ViewportState, VirtualListProps, VirtualListRef } from "./types";
+import { useTerminalSize } from "./useTerminalSize";
+
+const DEFAULT_HEIGHT = 10;
+const DEFAULT_ITEM_HEIGHT = 1;
+
+function calculateViewportOffset(selectedIndex: number, currentOffset: number, visibleCount: number): number {
+  // Selection above viewport - scroll up
+  if (selectedIndex < currentOffset) {
+    return selectedIndex;
+  }
+
+  // Selection below viewport - scroll down
+  if (selectedIndex >= currentOffset + visibleCount) {
+    return selectedIndex - visibleCount + 1;
+  }
+
+  // Selection visible - no change
+  return currentOffset;
+}
+
+function VirtualListInner<T>(props: VirtualListProps<T>, ref: React.ForwardedRef<VirtualListRef>): React.JSX.Element {
+  const {
+    items,
+    renderItem,
+    selectedIndex = 0,
+    keyExtractor,
+    height = DEFAULT_HEIGHT,
+    reservedLines = 0,
+    itemHeight = DEFAULT_ITEM_HEIGHT,
+    showOverflowIndicators = true,
+    renderOverflowTop,
+    renderOverflowBottom,
+    renderScrollBar,
+    onViewportChange,
+  } = props;
+
+  const { rows: terminalRows } = useTerminalSize();
+
+  // Calculate resolved height
+  const resolvedHeight = useMemo(() => {
+    if (typeof height === "number") {
+      return height;
+    }
+    // 'auto' - use terminal rows minus reserved
+    return Math.max(1, terminalRows - reservedLines);
+  }, [height, terminalRows, reservedLines]);
+
+  const resolvedItemHeight = itemHeight ?? DEFAULT_ITEM_HEIGHT;
+
+  // Reserve space for overflow indicators within the height budget
+  const indicatorLines = showOverflowIndicators ? 2 : 0;
+  const availableHeight = Math.max(0, resolvedHeight - indicatorLines);
+
+  // Calculate how many items fit in viewport
+  const visibleCount = Math.floor(availableHeight / resolvedItemHeight);
+
+  // Clamp selectedIndex to valid range
+  const clampedSelectedIndex = Math.max(0, Math.min(selectedIndex, items.length - 1));
+
+  // Calculate viewport offset - use useMemo to derive from selectedIndex
+  // This ensures the viewport is always in sync with selection
+  const calculatedOffset = useMemo(() => {
+    if (items.length === 0) return 0;
+
+    const maxOffset = Math.max(0, items.length - visibleCount);
+
+    // Calculate what offset would show the selected item
+    let offset = 0;
+
+    // Selection below viewport - scroll down
+    if (clampedSelectedIndex >= visibleCount) {
+      offset = clampedSelectedIndex - visibleCount + 1;
+    }
+
+    return Math.min(Math.max(0, offset), maxOffset);
+  }, [items.length, visibleCount, clampedSelectedIndex]);
+
+  const [viewportOffset, setViewportOffset] = useState(calculatedOffset);
+
+  // Sync viewportOffset when selection changes
+  useEffect(() => {
+    const newOffset = calculateViewportOffset(clampedSelectedIndex, viewportOffset, visibleCount);
+    if (newOffset !== viewportOffset) {
+      const maxOffset = Math.max(0, items.length - visibleCount);
+      setViewportOffset(Math.min(newOffset, maxOffset));
+    }
+  }, [clampedSelectedIndex, viewportOffset, visibleCount, items.length]);
+
+  // Build viewport state
+  const viewport: ViewportState = useMemo(
+    () => ({
+      offset: viewportOffset,
+      visibleCount,
+      totalCount: items.length,
+    }),
+    [viewportOffset, visibleCount, items.length],
+  );
+
+  // Notify on viewport change
+  useEffect(() => {
+    onViewportChange?.(viewport);
+  }, [viewport, onViewportChange]);
+
+  // Imperative handle
+  useImperativeHandle(
+    ref,
+    () => ({
+      scrollToIndex: (index: number, alignment: "auto" | "top" | "center" | "bottom" = "auto") => {
+        const clampedIndex = Math.max(0, Math.min(index, items.length - 1));
+        let newOffset: number;
+
+        switch (alignment) {
+          case "top":
+            newOffset = clampedIndex;
+            break;
+          case "center":
+            newOffset = clampedIndex - Math.floor(visibleCount / 2);
+            break;
+          case "bottom":
+            newOffset = clampedIndex - visibleCount + 1;
+            break;
+          default: // 'auto'
+            newOffset = calculateViewportOffset(clampedIndex, viewportOffset, visibleCount);
+        }
+
+        const maxOffset = Math.max(0, items.length - visibleCount);
+        setViewportOffset(Math.min(Math.max(0, newOffset), maxOffset));
+      },
+      getViewport: () => viewport,
+      remeasure: () => {
+        // Force recalculation by updating state
+        setViewportOffset((prev) => {
+          const maxOffset = Math.max(0, items.length - visibleCount);
+          return Math.min(prev, maxOffset);
+        });
+      },
+    }),
+    [items.length, visibleCount, viewportOffset, viewport],
+  );
+
+  // Calculate overflow counts
+  const overflowTop = viewportOffset;
+  const overflowBottom = Math.max(0, items.length - viewportOffset - visibleCount);
+
+  // Get visible items
+  const visibleItems = items.slice(viewportOffset, viewportOffset + visibleCount);
+
+  // Default overflow renderers (paddingLeft aligns with list content)
+  const defaultOverflowTop = (count: number) => (
+    <Box paddingLeft={2}>
+      <Text dimColor>▲ {count} more</Text>
+    </Box>
+  );
+  const defaultOverflowBottom = (count: number) => (
+    <Box paddingLeft={2}>
+      <Text dimColor>▼ {count} more</Text>
+    </Box>
+  );
+
+  const topIndicator = renderOverflowTop ?? defaultOverflowTop;
+  const bottomIndicator = renderOverflowBottom ?? defaultOverflowBottom;
+
+  return (
+    <Box flexDirection="column">
+      {showOverflowIndicators && overflowTop > 0 && topIndicator(overflowTop)}
+
+      {visibleItems.map((item, idx) => {
+        const actualIndex = viewportOffset + idx;
+        const key = keyExtractor ? keyExtractor(item, actualIndex) : String(actualIndex);
+
+        const itemProps: RenderItemProps<T> = {
+          item,
+          index: actualIndex,
+          isSelected: actualIndex === clampedSelectedIndex,
+        };
+
+        return <Box key={key}>{renderItem(itemProps)}</Box>;
+      })}
+
+      {showOverflowIndicators && overflowBottom > 0 && bottomIndicator(overflowBottom)}
+
+      {renderScrollBar?.(viewport)}
+    </Box>
+  );
+}
+
+export const VirtualList = forwardRef(VirtualListInner) as <T>(
+  props: VirtualListProps<T> & { ref?: React.ForwardedRef<VirtualListRef> },
+) => ReturnType<typeof VirtualListInner>;

package/src/index.ts

@@ -0,0 +1,9 @@
+export type {
+  RenderItemProps,
+  ViewportState,
+  VirtualListProps,
+  VirtualListRef,
+} from "./types";
+export type { TerminalSize } from "./useTerminalSize";
+export { useTerminalSize } from "./useTerminalSize";
+export { VirtualList } from "./VirtualList";

package/src/types.ts

@@ -0,0 +1,72 @@
+import type { ReactNode } from "react";
+
+/**
+ * Props passed to the renderItem function for each visible item.
+ */
+export interface RenderItemProps<T> {
+  /** The item data from the items array */
+  item: T;
+  /** The index of this item in the full items array */
+  index: number;
+  /** Whether this item is currently selected */
+  isSelected: boolean;
+}
+
+/**
+ * Represents the current viewport state of the virtual list.
+ */
+export interface ViewportState {
+  /** Number of items scrolled past (hidden above viewport) */
+  offset: number;
+  /** Number of items currently visible in the viewport */
+  visibleCount: number;
+  /** Total number of items in the list */
+  totalCount: number;
+}
+
+/**
+ * Props for the VirtualList component.
+ */
+export interface VirtualListProps<T> {
+  /** Array of items to render */
+  items: T[];
+  /** Render function for each visible item */
+  renderItem: (props: RenderItemProps<T>) => ReactNode;
+
+  /** Index of the currently selected item (default: 0) */
+  selectedIndex?: number;
+  /** Function to extract a unique key for each item */
+  keyExtractor?: (item: T, index: number) => string;
+
+  /** Fixed height in lines, or "auto" to fill available terminal space (default: 10) */
+  height?: number | "auto";
+  /** Lines to reserve when using height="auto" (e.g., for headers/footers) */
+  reservedLines?: number;
+  /** Height of each item in lines (default: 1) */
+  itemHeight?: number;
+
+  /** Whether to show "N more" indicators when items overflow (default: true) */
+  showOverflowIndicators?: boolean;
+  /** Custom renderer for the top overflow indicator */
+  renderOverflowTop?: (count: number) => ReactNode;
+  /** Custom renderer for the bottom overflow indicator */
+  renderOverflowBottom?: (count: number) => ReactNode;
+
+  /** Custom renderer for a scrollbar (receives viewport state) */
+  renderScrollBar?: (viewport: ViewportState) => ReactNode;
+
+  /** Callback fired when the viewport changes */
+  onViewportChange?: (viewport: ViewportState) => void;
+}
+
+/**
+ * Imperative handle methods exposed via ref.
+ */
+export interface VirtualListRef {
+  /** Scroll to bring a specific index into view */
+  scrollToIndex: (index: number, alignment?: "auto" | "top" | "center" | "bottom") => void;
+  /** Get the current viewport state */
+  getViewport: () => ViewportState;
+  /** Force recalculation of viewport dimensions */
+  remeasure: () => void;
+}

package/src/useTerminalSize.ts

@@ -0,0 +1,43 @@
+import { useStdout } from "ink";
+import { useEffect, useState } from "react";
+
+/**
+ * Represents the terminal dimensions.
+ */
+export interface TerminalSize {
+  /** Number of rows (lines) in the terminal */
+  rows: number;
+  /** Number of columns (characters) in the terminal */
+  columns: number;
+}
+
+const DEFAULT_ROWS = 24;
+const DEFAULT_COLUMNS = 80;
+
+/**
+ * Hook that returns the current terminal size and updates on resize.
+ * Uses Ink's stdout to detect terminal dimensions.
+ */
+export function useTerminalSize(): TerminalSize {
+  const { stdout } = useStdout();
+  const [size, setSize] = useState<TerminalSize>({
+    rows: stdout.rows ?? DEFAULT_ROWS,
+    columns: stdout.columns ?? DEFAULT_COLUMNS,
+  });
+
+  useEffect(() => {
+    const handleResize = () => {
+      setSize({
+        rows: stdout.rows ?? DEFAULT_ROWS,
+        columns: stdout.columns ?? DEFAULT_COLUMNS,
+      });
+    };
+
+    stdout.on("resize", handleResize);
+    return () => {
+      stdout.off("resize", handleResize);
+    };
+  }, [stdout]);
+
+  return size;
+}