@byteland/ink-scroll-bar

📜 ink-scroll-bar

A customizable, high-precision vertical scroll bar component for Ink CLI applications.

✨ Features

• Two Rendering Modes:

  • Border Mode: Seamlessly integrates with container borders (replaces one side).

    

  • Inset Mode: Renders inside the content area, perfect for floating scroll bars.

    

    • Supports autoHide: Completely hide the scroll bar when content fits the viewport.
    • If autoHide is false (default) and content fits, only the track is shown.

    

• Rich Styling:

  • Supports all standard Ink border styles (single, double, round, bold, etc.).
  • Special inset styles (block, line, thick, dots).
  • Customizable colors and dimming.

• Flexible Integration:

  • Standalone ScrollBar component for custom layouts.
  • ScrollBarBox wrapper for instant bordered containers with scroll bars.

• Auto-hide: Option to hide the scroll bar when content fits the viewport (inset mode).

📦 Installation

npm install @byteland/ink-scroll-bar

🚀 Usage

Basic Usage with ScrollBarBox

The easiest way to use ink-scroll-bar is with the ScrollBarBox component. It wraps your content in a bordered box and handles the scroll bar positioning for you.

import React, { useState } from "react";
import { Text } from "ink";
import { ScrollBarBox } from "ink-scroll-bar";

const MyComponent = () => {
  const [offset, setOffset] = useState(0);
  const totalItems = 50;
  const viewportHeight = 10;

  return (
    <ScrollBarBox
      height={viewportHeight + 2} // +2 for borders
      width={40}
      borderStyle="single"
      scrollBarPosition="right"
      contentHeight={totalItems}
      viewportHeight={viewportHeight}
      scrollOffset={offset}
    >
      {/* Your scrollable content here */}
      <Text>Item 1...</Text>
    </ScrollBarBox>
  );
};

Advanced Usage with ScrollBar

For more control over layout, use the standalone ScrollBar component.

Border Mode

In border mode, the scroll bar renders corner characters to connect with adjacent borders.

import { Box } from "ink";
import { ScrollBar } from "ink-scroll-bar";

<Box flexDirection="row">
  {/* Content Box with right border removed */}
  <Box borderStyle="single" borderRight={false}>
    <Content />
  </Box>

  {/* ScrollBar completes the border */}
  <ScrollBar
    placement="right"
    style="single"
    contentHeight={100}
    viewportHeight={20}
    scrollOffset={offset}
  />
</Box>;

Inset Mode

Inset mode renders without corners, suitable for placing inside a container.

<Box borderStyle="round" padding={1}>
  <Box flexDirection="row">
    <Content />
    <ScrollBar
      placement="inset"
      style="block" // 'block', 'line', 'thick', 'dots'
      color="cyan"
      contentHeight={100}
      viewportHeight={20}
      scrollOffset={offset}
      autoHide // Hide if content fits
    />
  </Box>
</Box>

📚 API

ScrollBar Props

Prop	Type	Default	Description
contentHeight	number	Required	📏 Total height of the scrollable content.
viewportHeight	number	Required	👁️ Height of the visible area.
scrollOffset	number	Required	⬇️ Current scroll position (0 to max).
placement	'left' | 'right' | 'inset'	'right'	📍 Rendering mode/position.
style	ScrollBarStyle	'single'/'block'	🎨 Visual style (see below).
color	string	undefined	🌈 Color of the scroll bar characters.
dimColor	boolean	false	🌑 Whether to dim the scroll bar.
autoHide	boolean	false	👻 Hide when content fits (Inset mode only). If false, shows track when content fits.
thumbChar	string	-	👍 Custom thumb character.
trackChar	string	-	🛤️ Custom track character (Inset mode only).

ScrollBarBox Props

Inherits all Ink Box Props, plus:

Prop	Type	Default	Description
contentHeight	number	Required	📏 Total height of the content.
viewportHeight	number	Required	👁️ Height of the viewport.
scrollOffset	number	Required	⬇️ Current scroll position.
scrollBarPosition	'left' | 'right'	'right'	📍 Which border to replace with scroll bar.
scrollBarAutoHide	boolean	false	👻 Hide thumb if content fits.
thumbChar	string	-	👍 Custom thumb character.

🎨 Styles

Border Mode Styles (matches Ink borders):

• single, double, round, bold, singleDouble, doubleSingle, classic, arrow

Inset Mode Styles:

• block: █ thumb, ░ track
• line: │ thumb, (blank) track
• thick: ┃ thumb, ╏ track
• dots: ● thumb, · track

📄 License

MIT