On this page

ScrollBox

ScrollBox scrolls arbitrary child renderables and manages its own ScrollBar instances. Use a standalone ScrollBar only when another model owns the scroll position.

Availability#

Field Availability
Package @opentui/core
Core renderable ScrollBoxRenderable
React <scrollbox> (automatic)
Solid <scrollbox> (automatic)
Status Built in

Basic usage#

Renderable API#

import { ScrollBoxRenderable, TextRenderable, BoxRenderable, createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer()

const scrollbox = new ScrollBoxRenderable(renderer, {
  id: "scrollbox",
  width: 40,
  height: 20,
})

// Add content to the scrollbox
for (let i = 0; i < 100; i++) {
  scrollbox.add(
    new BoxRenderable(renderer, {
      id: `item-${i}`,
      width: "100%",
      height: 2,
      backgroundColor: i % 2 === 0 ? "#292e42" : "#2f3449",
    }),
  )
}

renderer.root.add(scrollbox)

A bordered list of source files initially shows its first five rows:

Sticky scroll#

Enable sticky scroll to keep content pinned to an edge as new content arrives. Set both stickyScroll and stickyStart because stickyStart has no default.

const scrollbox = new ScrollBoxRenderable(renderer, {
  id: "logs",
  width: 60,
  height: 20,
  stickyScroll: true,
  stickyStart: "bottom", // New content will keep the view scrolled to bottom
})

Sticky positions#

  • "bottom": Stay scrolled to the bottom
  • "top": Stay scrolled to the top
  • "left": Stay scrolled to the left
  • "right": Stay scrolled to the right

When you scroll away from the sticky position, sticky behavior pauses until you scroll back to the sticky edge.

Bidirectional scrolling#

Enable scrolling in both directions:

const scrollbox = new ScrollBoxRenderable(renderer, {
  id: "canvas",
  width: 60,
  height: 30,
  scrollX: true,
  scrollY: true,
})

By default, scrollY is true and scrollX is false.

Viewport culling#

Enable viewport culling to skip offscreen children in large content. When enabled, ScrollBox renders only visible children:

const scrollbox = new ScrollBoxRenderable(renderer, {
  id: "large-list",
  width: 40,
  height: 20,
  viewportCulling: true, // Only render visible items
})

Viewport culling skips render calls for offscreen children, so their renderBefore and renderAfter hooks do not run. Do not make layout or state depend on render hooks. Disable viewportCulling if every child must run a render hook.

Customizing scrollbars#

Style the scrollbars using nested options:

const scrollbox = new ScrollBoxRenderable(renderer, {
  id: "styled-scroll",
  width: 40,
  height: 20,
  scrollbarOptions: {
    showArrows: true,
    trackOptions: {
      foregroundColor: "#7aa2f7",
      backgroundColor: "#414868",
    },
  },
  // Or customize vertical and horizontal separately
  verticalScrollbarOptions: {
    trackOptions: { backgroundColor: "#333" },
  },
  horizontalScrollbarOptions: {
    trackOptions: { backgroundColor: "#333" },
  },
})

Customizing sub-components#

ScrollBox contains several internal components that you can style individually:

const scrollbox = new ScrollBoxRenderable(renderer, {
  id: "custom-scroll",
  width: 40,
  height: 20,
  rootOptions: {
    backgroundColor: "#24283b",
  },
  wrapperOptions: {
    backgroundColor: "#1f2335",
  },
  viewportOptions: {
    backgroundColor: "#1a1b26",
  },
  contentOptions: {
    backgroundColor: "#16161e",
  },
})

Scroll methods#

scrollBy#

Scroll by a relative amount:

// Scroll down 5 lines
scrollbox.scrollBy(5)

// Scroll with both x and y
scrollbox.scrollBy({ x: 10, y: 5 })

// Scroll by viewport (page)
scrollbox.scrollBy(1, "viewport")

scrollTo#

Scroll to an absolute position:

// Scroll to top
scrollbox.scrollTo(0)

// Scroll to specific position
scrollbox.scrollTo({ x: 0, y: 100 })

The same list after scrollTo(5):

scrollChildIntoView#

Scroll the minimum distance needed to show a nested child in the viewport. The method uses DOM-style “nearest” behavior. If the child already fits, the call is a no-op. An oversized child also stays in place when it extends beyond both edges of an axis. Otherwise, the method scrolls to reveal the nearest edge.

scrollbox.scrollChildIntoView("table-row-42")

Use it when you focus an offscreen element, such as a search result or a new form field. The method moves the scroll position only as much as necessary.

Keyboard navigation#

When focused, ScrollBox responds to keyboard input:

  • Arrow keys: Move by one fifth of the active viewport.
  • Page Up/Down: Move by one half of the vertical viewport.
  • Home/End: Move to the start or end.

Properties#

Property Type Default Description
scrollX boolean false Enable horizontal scrolling
scrollY boolean true Enable vertical scrolling
stickyScroll boolean false Keep scroll position pinned to an edge
stickyStart "top" | "bottom" | "left" | "right" - Which edge to stick to
viewportCulling boolean true Only render visible children
scrollAcceleration ScrollAcceleration - Custom scroll acceleration algorithm
rootOptions BoxOptions - Style options for root container
wrapperOptions BoxOptions - Style options for wrapper
viewportOptions BoxOptions - Style options for viewport
contentOptions BoxOptions - Style options for content container
scrollbarOptions ScrollBarOptions - Options for both scrollbars
verticalScrollbarOptions ScrollBarOptions - Options for vertical scrollbar only
horizontalScrollbarOptions ScrollBarOptions - Options for horizontal scrollbar only

Additional properties#

Property Type Description
scrollTop number Current vertical scroll position (get/set)
scrollLeft number Current horizontal scroll position (get/set)
scrollWidth number Total scrollable width (read-only)
scrollHeight number Total scrollable height (read-only)

Internal components#

ScrollBox exposes its internal components for advanced use:

scrollbox.wrapper // BoxRenderable - outer wrapper
scrollbox.viewport // BoxRenderable - visible area
scrollbox.content // ContentRenderable - holds children
scrollbox.horizontalScrollBar // ScrollBarRenderable
scrollbox.verticalScrollBar // ScrollBarRenderable

Read Layout for viewport sizing. Read Interaction, focus, and selection for focus, wheel input, drag selection, and event propagation.