Viewport [proxy]

API reference for the Viewport component

A scrollable container that clips content to a fixed height and scrolls by row. Inspired by Bubble Tea's viewport and ink-scroll-view.

Pass any children — text, components, mixed content. Viewport measures each child's actual rendered height after terminal wrapping, so long lines that wrap across multiple rows are accounted for correctly without any manual line-splitting. Use the ref to programmatically scroll or jump to a specific child with scrollToItem. For a virtualized item-count-based list, see VirtualList.

import { Viewport } from 'giggles/ui';

function ArticleViewer({ paragraphs }: { paragraphs: string[] }) {
  return (
    <Viewport height={20}>
      {paragraphs.map((p, i) => (
        <Text key={i}>{p}</Text>
      ))}
    </Viewport>
  );
}

Viewport

Prop

Type

ViewportRef

Control scrolling programmatically via a ref.

import { useRef } from 'react';
import { Viewport, ViewportRef } from 'giggles/ui';

const ref = useRef<ViewportRef>(null);

ref.current?.scrollToItem(5);
ref.current?.scrollBy(3);
ref.current?.scrollToTop();

Prop

Type

Keybindings

Key	Action
`j` / `↓`	Scroll down one row
`k` / `↑`	Scroll up one row
`PgDn`	Scroll down one page
`PgUp`	Scroll up one page
`g`	Jump to top
`G`	Jump to bottom
`Tab` / `Shift+Tab`	Move to next/previous component

Mixed content

<Viewport height={15}>
  <Text bold>Log Output</Text>
  <Text dimColor>─────────</Text>
  {entries.map((entry, i) => (
    <Text key={i} color={entry.level === 'error' ? 'red' : 'yellow'}>
      [{entry.level}] {entry.message}
    </Text>
  ))}
</Viewport>