Skip to Content
DocsAPI ReferenceInterfacesScrollListRef

ink-scroll-list

Interface: ScrollListRef

Ref interface for controlling the ScrollList programmatically.

Remarks

Extends ScrollViewRef  from ink-scroll-view. Since selection is now controlled externally via props, this interface no longer includes selection-related methods.

Scroll Constraint Behavior: When a selectedIndex is set, all scroll methods (scrollTo, scrollBy, scrollToTop, scrollToBottom) are constrained to keep the selected item visible in the viewport. This prevents accidentally scrolling the selection out of view.

For items larger than the viewport, scrolling is allowed within the item’s bounds, letting users view different parts of the large item while keeping at least part of it visible.

Available Methods (inherited from ScrollViewRef):

  • scrollTo(y): Scroll to a specific offset (constrained if selected item exists)
  • scrollBy(delta): Scroll by a relative amount (constrained)
  • scrollToTop(): Scroll as far up as possible while keeping selection visible
  • scrollToBottom(): Scroll as far down as possible while keeping selection visible
  • getScrollOffset(): Get the current scroll offset
  • getContentHeight(): Get the total content height
  • getViewportHeight(): Get the viewport height
  • getBottomOffset(): Get the offset from the bottom
  • getItemHeight(index): Get a specific item’s height
  • getItemPosition(index): Get a specific item’s position (top and height)
  • remeasure(): Re-check viewport dimensions
  • remeasureItem(index): Force remeasurement of a specific item

Note: Unlike previous versions, there are no selection methods (select, selectNext, etc.) as selection is now controlled externally via the selectedIndex prop.

Extends

Properties

getBottomOffset()

getBottomOffset: () => number

Gets the scroll offset when the content is scrolled to the very bottom.

Returns

number

The bottom scroll offset in terminal rows.

Remarks

This is calculated as contentHeight - viewportHeight. When the scroll offset equals this value, the last item of the content is visible at the bottom of the viewport.

Inherited from

ScrollViewRef.getBottomOffset

getContentHeight()

getContentHeight: () => number

Gets the total height of the content.

Returns

number

The total content height in terminal rows.

Remarks

This is the sum of the heights of all child items.

Inherited from

ScrollViewRef.getContentHeight

getItemHeight()

getItemHeight: (index) => number

Gets the height of a specific item by its index.

Parameters

index

number

The index of the item.

Returns

number

The height of the item in terminal rows, or 0 if not found.

Inherited from

ScrollViewRef.getItemHeight

getItemPosition()

getItemPosition: (index) => { height: number; top: number; } | null

Gets the position of a specific item.

Parameters

index

number

The index of the item.

Returns

{ height: number; top: number; } | null

The position (top offset) and height of the item, or null if not found.

Inherited from

ScrollViewRef.getItemPosition

getScrollOffset()

getScrollOffset: () => number

Gets the current scroll offset (distance scrolled from the top).

Returns

number

The current scroll offset in terminal rows.

Remarks

The scroll offset represents how many terminal rows the content has been scrolled up from its initial position. A value of 0 means the content is at the very top (no scrolling has occurred).

Inherited from

ScrollViewRef.getScrollOffset

getViewportHeight()

getViewportHeight: () => number

Gets the current height of the visible viewport.

Returns

number

The viewport height in terminal rows.

Inherited from

ScrollViewRef.getViewportHeight

remeasure()

remeasure: () => void

Re-checks the viewport dimensions and updates them if they have changed.

Returns

void

Remarks

Viewport layout changes are tracked automatically, including parent layout changes and terminal resizes. This method does not force item measurement. Use ScrollListRef.remeasureItem to re-measure a specific item.

Overrides

ScrollViewRef.remeasure

remeasureItem()

remeasureItem: (index) => void

Triggers remeasurement of a specific item.

Parameters

index

number

Index of the item to re-measure.

Returns

void

Remarks

Use this after an item’s internal state update has committed if its height changed without changing the measuring wrapper’s inputs, such as its child element or viewport width.

Overrides

ScrollViewRef.remeasureItem

scrollBy()

scrollBy: (delta) => void

Scrolls by a relative amount.

Parameters

delta

number

Positive for down, negative for up.

Returns

void

Example

useInput((input, key) => {
  if (key.downArrow) ref.current?.scrollBy(1);
  if (key.upArrow) ref.current?.scrollBy(-1);
});

Inherited from

ScrollViewRef.scrollBy

scrollTo()

scrollTo: (offset) => void

Scrolls to a specific vertical position.

Parameters

offset

number

The target Y offset (distance from top).

Returns

void

Example

// Scroll to the very top
ref.current?.scrollTo(0);

Inherited from

ScrollViewRef.scrollTo

scrollToBottom()

scrollToBottom: () => void

Scrolls to the very bottom.

Returns

void

Remarks

This calculates the target offset as contentHeight - viewportHeight.

Inherited from

ScrollViewRef.scrollToBottom

scrollToTop()

scrollToTop: () => void

Scrolls to the very top (position 0).

Returns

void

Inherited from

ScrollViewRef.scrollToTop

ScrollListPropsScrollAlignment