Skip to main content

​
Overview

The ScrollBox widget creates a scrollable viewport for content that exceeds the container’s size. It supports both horizontal and vertical scrolling and can contain exactly one child widget.

​
Constructor

const scrollbox = new ScrollBox(options?: ScrollBoxOptions);

​
ScrollBoxOptions

​
width
string | number
Width of the scrollbox viewport. Accepts:
  • Number: fixed width in cells
  • String: percentage (e.g., "50%") or "auto"
​
height
string | number
Height of the scrollbox viewport. Accepts:
  • Number: fixed height in rows
  • String: percentage (e.g., "100%") or "auto"
​
border
string
Border style. Valid values:
  • "none" - no border
  • "single" - single-line border
  • "double" - double-line border
  • "rounded" - rounded corners
  • "bold" - bold border
​
fg
string | number
Foreground (border/scrollbar) color. Accepts:
  • Hex string: "#FF0000"
  • Color name: "red", "blue", etc.
  • 256-color code: 196
​
bg
string | number
Background color. Same format as fg.

​
Methods

​
setScroll()

Set the absolute scroll position. 
setScroll(x: number, y: number): void
​
x
number
Horizontal scroll position in cells. 0 is the leftmost position.
​
y
number
Vertical scroll position in rows. 0 is the topmost position.
Source: ts/src/widgets/scrollbox.ts:27

​
getScroll()

Get the current scroll position. 
getScroll(): { x: number; y: number }
​
return
object
Object containing:
  • x - Horizontal scroll position in cells
  • y - Vertical scroll position in rows
Source: ts/src/widgets/scrollbox.ts:31

​
scrollBy()

Scroll relative to the current position. 
scrollBy(dx: number, dy: number): void
​
dx
number
Amount to scroll horizontally. Positive values scroll right, negative scroll left.
​
dy
number
Amount to scroll vertically. Positive values scroll down, negative scroll up.
Source: ts/src/widgets/scrollbox.ts:38

​
Examples

import { ScrollBox, Box, Text } from "kraken-tui";

const scrollbox = new ScrollBox({
  width: 50,
  height: 20,
  border: "single",
});

// Create large content
const content = new Box({
  width: 100,
  height: 50,
  flexDirection: "column",
});

for (let i = 0; i < 50; i++) {
  content.append(new Text({ content: `Line ${i + 1}` }));
}

scrollbox.append(content);

// Scroll to specific position
scrollbox.setScroll(0, 10);

​
Inherited Methods

ScrollBox inherits all methods from the Widget base class, including:
  • append(child) - Add the single child widget
  • removeChild(child) - Remove the child widget
  • setVisible(visible) - Control visibility
  • destroy() - Clean up resources
See the Widget API reference for the complete list.

​
Event Handling

ScrollBox widgets typically respond to keyboard events for navigation:
  • Arrow keys - Scroll in direction
  • Page Up/Down - Scroll larger increments
  • Home/End - Jump to top/bottom
Implement event handling in your application event loop using app.drainEvents().

​
Single-Child Constraint

ScrollBox can contain exactly one child widget. If you need to scroll multiple widgets:
  1. Create a container Box
  2. Add your widgets to the Box
  3. Add the Box as the child of ScrollBox
const scrollbox = new ScrollBox({ width: 50, height: 20 });
const container = new Box({ flexDirection: "column" });

container.append(widget1);
container.append(widget2);
container.append(widget3);

scrollbox.append(container);

​
Notes

  • ScrollBox supports both horizontal and vertical scrolling
  • Scroll position is automatically clamped to content bounds
  • Scrollbars are displayed automatically when content exceeds viewport
  • Use scrollBy() for relative scrolling (e.g., in response to arrow keys)
  • Use setScroll() for absolute positioning (e.g., jump to specific line)
  • The single child widget can be arbitrarily large
  • Scrolling is handled by the native layer for performance

Build docs developers (and LLMs) love

Get started for freeTalk to us