ink-scroll-view

ink-scroll-view

A robust, performance-optimized ScrollView component for Ink CLI applications.

✨ Features

• 📦 Flexible Container: Handles content larger than the visible terminal viewport.
• ⚡ Performance First:
  • Optimistic Updates: Immediate state updates for smoother interaction.
  • Efficient Re-rendering: Renders all children but strictly manages visibility via overflow and offsets, ensuring correct layout without layout thrashing.
• 📏 Auto-Measurement: Automatically measures child heights using a virtually rendered DOM.
• 🔁 Dynamic Content: Supports adding, removing, and expanding/collapsing items on the fly.
• ⚓️ Layout Stability: Includes logic to maintain scroll position context when content changes.

📦 Installation

npm install ink-scroll-view
# Peer dependencies
npm install ink react

🚀 Usage

ScrollView is a layout primitive. It does not capture user input automatically. You must control it programmatically using React refs and Ink's useInput.

import React, { useRef, useEffect } from "react";
import { render, Text, Box, useInput, useStdout } from "ink";
import { ScrollView, ScrollViewRef } from "ink-scroll-view";

const App = () => {
  const scrollRef = useRef<ScrollViewRef>(null);
  const { stdout } = useStdout();

  // 1. Handle Terminal Resizing due to manual window change
  useEffect(() => {
    const handleResize = () => scrollRef.current?.remeasure();
    stdout?.on("resize", handleResize);
    return () => {
      stdout?.off("resize", handleResize);
    };
  }, [stdout]);

  // 2. Handle Keyboard Input
  useInput((input, key) => {
    if (key.upArrow) {
      scrollRef.current?.scrollBy(-1); // Scroll up 1 line
    }
    if (key.downArrow) {
      scrollRef.current?.scrollBy(1); // Scroll down 1 line
    }
    if (key.pageUp) {
      // Scroll up by viewport height
      const height = scrollRef.current?.getViewportHeight() || 1;
      scrollRef.current?.scrollBy(-height);
    }
    if (key.pageDown) {
      const height = scrollRef.current?.getViewportHeight() || 1;
      scrollRef.current?.scrollBy(height);
    }
  });

  return (
    <Box
      height={10}
      width="100%"
      borderStyle="single"
      borderColor="green"
      flexDirection="column"
    >
      <ScrollView ref={scrollRef}>
        {Array.from({ length: 50 }).map((_, i) => (
          <Text key={i}>Item {i + 1} - content with variable length...</Text>
        ))}
      </ScrollView>
    </Box>
  );
};

render(<App />);

📐 How it Works

The component renders all children into a container but shifts the content vertically using marginTop. The parent box with overflow="hidden" acts as the "viewport".

┌─────────────────────────┐
│  (hidden content)       │ ← Content above viewport
│  ...                    │
├─────────────────────────┤ ← scrollOffset (distance from top)
│  ┌───────────────────┐  │
│  │ Visible Viewport  │  │ ← What user sees
│  │                   │  │
│  └───────────────────┘  │
├─────────────────────────┤
│  (hidden content)       │ ← Content below viewport
│  ...                    │
└─────────────────────────┘

📚 API Reference

Props (ScrollViewProps)

Inherits standard BoxProps from Ink.

Prop	Type	Description
children	ReactElement[]	Required. List of child elements. Must use unique keys (strings/numbers).
onScroll	(offset: number) => void	Called when scroll position changes.
onViewportSizeChange	(layout: { width, height }) => void	Called when the viewport dimensions change.
onContentHeightChange	(height: number) => void	Called when the total content height changes.
onItemHeightChange	(index: number, height: number) => void	Called when an individual item's height changes.
...	BoxProps	Any other prop accepted by Ink's Box.

Ref Methods (ScrollViewRef)

Access these via ref.current.

Method	Signature	Description
scrollTo	(offset: number) => void	Scrolls to an absolute Y offset from the top.
scrollBy	(delta: number) => void	Scrolls by a relative amount (negative = up, positive = down).
scrollToTop	() => void	Helper to scroll to offset 0.
scrollToBottom	() => void	Helper to scroll to the maximum possible offset (contentHeight - viewportHeight).
getScrollOffset	() => number	Returns the current scroll offset.
getContentHeight	() => number	Returns the total height of all content items.
getViewportHeight	() => number	Returns the current height of the visible area.
getItemHeight	(index: number) => number	Returns the measured height of a specific item by its index.
getItemPosition	(index: number) => { top, height }	Returns the position (top offset) and height of a specific item.
remeasure	() => void	Re-checks viewport dimensions. Must call this on terminal resize.
remeasureItem	(index: number) => void	Forces a specific child to re-measure. Useful for dynamic content (expand/collapse) that doesn't trigger a full re-render.

💡 Tips

• Unique Keys: Always provide stable, unique key props (strings or numbers) to your children. This allows ScrollView to accurately track height changes even when items are re-ordered or removed.
• Terminal Resizing: Ink components don't automatically know when the terminal window resizes. You need to listen to process.stdout's resize event and call remeasure() on the ref.
• Dynamic Content: If you have an item that expands (e.g., "See more"), calling remeasureItem(index) is more efficient than forcing a full update.

License

MIT