A vertical ScrollBar component for Ink CLI applications
npm install @byteland/ink-scroll-barA customizable, high-precision vertical scroll bar component for Ink CLI applications.
- 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.
!Inset Mode Demo
- 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).
``bash`
npm install ink-scroll-bar
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.
`tsx
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 (
width={40}
borderStyle="single"
scrollBarPosition="right"
contentHeight={totalItems}
viewportHeight={viewportHeight}
scrollOffset={offset}
>
{/ Your scrollable content here /}
);
};
`
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.
`tsx
import { Box } from "ink";
import { ScrollBar } from "ink-scroll-bar";
{/ Content Box with right border removed /}
{/ ScrollBar completes the border /}
style="single"
contentHeight={100}
viewportHeight={20}
scrollOffset={offset}
/>
;
`
#### Inset Mode
Inset mode renders without corners, suitable for placing _inside_ a container.
`tsx`
style="block" // 'block', 'line', 'thick', 'dots'
color="cyan"
contentHeight={100}
viewportHeight={20}
scrollOffset={offset}
autoHide // Hide if content fits
/>
| Prop | Type | Default | Description |
| ---------------- | ------------------------------ | -------------------- | ------------------------------------------------------------------------------------- |
| contentHeight | number | Required | ๐ Total height of the scrollable content. |contentHeight
| Prop | Type | Default | Description |
| ---------------- | ------------------------------ | -------------------- | --------------------------------------------------------------------------- |
| | 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 (Inset mode only). |trackChar
| | string | - | ๐ค๏ธ Custom track character (Inset mode only). |
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. |
Border Mode Styles (matches Ink borders):
- single, double, round, bold, singleDouble, doubleSingle, classic, arrow
Inset Mode Styles:
- block: โ thumb, โ trackline
- : โ thumb, (blank) trackthick
- : โ thumb, โ trackdots`: โ thumb, ยท track
-
MIT