claude-code/packages/@ant/ink/docs/06-scrolling.md

Chapter 6: Scrolling

ScrollBox

A scrollable container with imperative scroll API, viewport culling, and sticky scroll support.

import { ScrollBox } from '@anthropic/ink'
import type { ScrollBoxHandle } from '@anthropic/ink'

function MessageList({ messages }) {
  const scrollRef = useRef<ScrollBoxHandle>(null)

  // Auto-scroll to bottom on new messages
  useEffect(() => {
    scrollRef.current?.scrollToBottom()
  }, [messages.length])

  return (
    <ScrollBox ref={scrollRef} stickyScroll flexDirection="column" height={20}>
      {messages.map(msg => (
        <Text key={msg.id}>{msg.text}</Text>
      ))}
    </ScrollBox>
  )
}

Props

ScrollBox accepts all Box layout props except textWrap, overflow, overflowX, overflowY (these are managed internally):

Prop	Type	Default	Description
ref	Ref<ScrollBoxHandle>	-	Imperative handle
stickyScroll	boolean	false	Auto-follow new content
(layout props)	Styles	-	Width, height, padding, etc.

ScrollBoxHandle (Imperative API)

interface ScrollBoxHandle {
  // Absolute positioning
  scrollTo(y: number): void
  scrollToElement(el: DOMElement, offset?: number): void
  scrollToBottom(): void

  // Relative positioning
  scrollBy(dy: number): void

  // Query state
  getScrollTop(): number
  getPendingDelta(): number
  getScrollHeight(): number
  getFreshScrollHeight(): number
  getViewportHeight(): number
  getViewportTop(): number
  isSticky(): boolean

  // Events
  subscribe(listener: () => void): () => void

  // Virtual scroll support
  setClampBounds(min?: number, max?: number): void
}

Method Details

scrollTo(y)

Jump to an absolute position. Breaks sticky scroll.

scrollRef.current?.scrollTo(0)  // Scroll to top

scrollBy(dy)

Scroll by a relative amount. Accumulates deltas for smooth scrolling.

scrollRef.current?.scrollBy(3)   // Scroll down 3 rows
scrollRef.current?.scrollBy(-5)  // Scroll up 5 rows

scrollToElement(el, offset?)

Scroll so a specific DOM element is at the viewport top. More reliable than scrollTo because it reads the element's position at render time (avoids stale layout values).

const elementRef = useRef<DOMElement>(null)
scrollRef.current?.scrollToElement(elementRef.current!, 2)

scrollToBottom()

Pin scroll to bottom. Enables sticky mode.

scrollRef.current?.scrollToBottom()

isSticky()

Returns true when scroll is pinned to the bottom.

if (scrollRef.current?.isSticky()) {
  // User hasn't scrolled up
}

subscribe(listener)

Subscribe to imperative scroll changes. Returns unsubscribe function.

useEffect(() => {
  return scrollRef.current?.subscribe(() => {
    console.log('Scroll position changed')
  })
}, [])

Sticky Scroll

When stickyScroll is enabled:

1. Scroll automatically follows new content at the bottom
2. User scroll (via scrollBy/scrollTo) breaks stickiness
3. scrollToBottom() re-enables stickiness
4. Content growth at the bottom is detected and followed automatically

<ScrollBox stickyScroll height={20}>
  {/* New items auto-scroll to bottom */}
  {items.map(renderItem)}
</ScrollBox>

Viewport Culling

ScrollBox only renders children that intersect the visible viewport. Children outside the viewport are still mounted in React but skipped during terminal rendering. This makes large lists performant.

Virtual Scrolling

For very large lists, use setClampBounds in combination with a virtual scrolling hook:

const scrollRef = useRef<ScrollBoxHandle>(null)

// After computing visible range
scrollRef.current?.setClampBounds(firstVisibleRow, lastVisibleRow)

This prevents burst scrollTo calls from showing blank space beyond mounted content.

Scroll Events

ScrollBox bypasses React state for scroll operations. Instead:

1. scrollTo/scrollBy mutate scrollTop directly on the DOM node
2. The node is marked dirty
3. A microtask-deferred render fires to coalesce multiple scroll events
4. The Ink renderer reads scrollTop during layout

This avoids React reconciler overhead per wheel event.

Integration with Mouse Wheel

In alt-screen mode, mouse wheel events are captured by the App component and forwarded to the focused ScrollBox:

Wheel event → App.handleMouseEvent → ScrollBox.scrollBy(delta)

Layout Structure

ScrollBox creates a two-level DOM structure:

ink-box (overflow: scroll, constrained height)
└── Box (flexGrow: 1, flexShrink: 0, width: 100%)
    ├── Child 1
    ├── Child 2
    └── ...

The outer ink-box is the viewport with constrained size. The inner Box grows to fit all content. The renderer computes scrollHeight from the inner box and translates content by -scrollTop.