Skip to content

PyModel/pythinker-code / .agents/skills/opentui

opentui

Verified

Build terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.

FileKindSize
SKILL.mdskill md5.4 KB
docs/bindings/react.mdxmarkdown11.0 KB
docs/bindings/solid.mdxmarkdown15.0 KB
docs/components/ascii-font.mdxmarkdown4.3 KB
docs/components/box.mdxmarkdown5.5 KB
docs/components/code.mdxmarkdown10.2 KB
docs/components/diff.mdxmarkdown4.2 KB
docs/components/frame-buffer.mdxmarkdown6.7 KB
docs/components/input.mdxmarkdown5.6 KB
docs/components/line-number.mdxmarkdown4.0 KB
docs/components/markdown.mdxmarkdown10.6 KB
docs/components/qr-code.mdxmarkdown4.3 KB
docs/components/scrollbar.mdxmarkdown2.3 KB
docs/components/scrollbox.mdxmarkdown7.5 KB
docs/components/select.mdxmarkdown6.2 KB
docs/components/slider.mdxmarkdown2.2 KB
docs/components/tab-select.mdxmarkdown6.0 KB
docs/components/text-table.mdxmarkdown9.0 KB
docs/components/text.mdxmarkdown4.5 KB
docs/components/textarea.mdxmarkdown7.7 KB
docs/components/time-to-first-draw.mdxmarkdown4.7 KB
docs/core-concepts/audio.mdxmarkdown32.2 KB
docs/core-concepts/colors.mdxmarkdown7.8 KB
docs/core-concepts/console.mdxmarkdown3.2 KB
docs/core-concepts/constructs.mdxmarkdown5.8 KB
docs/core-concepts/keyboard.mdxmarkdown10.4 KB
docs/core-concepts/layout.mdxmarkdown4.0 KB
docs/core-concepts/lifecycle.mdxmarkdown4.4 KB
docs/core-concepts/notifications.mdxmarkdown2.3 KB
docs/core-concepts/renderables-vs-constructs.mdxmarkdown4.5 KB
docs/core-concepts/renderables.mdxmarkdown9.9 KB
docs/core-concepts/renderer.mdxmarkdown30.9 KB
docs/core-concepts/testing.mdxmarkdown14.6 KB
docs/getting-started.mdxmarkdown3.2 KB
docs/keymap/addons.mdxmarkdown15.6 KB
docs/keymap/core.mdxmarkdown38.9 KB
docs/keymap/custom-addons.mdxmarkdown26.7 KB
docs/keymap/hosts.mdxmarkdown15.7 KB
docs/keymap/overview.mdxmarkdown18.1 KB
docs/keymap/react.mdxmarkdown4.9 KB
docs/keymap/solid.mdxmarkdown5.1 KB
docs/plugins/core.mdxmarkdown12.6 KB
docs/plugins/react.mdxmarkdown6.5 KB
docs/plugins/slots.mdxmarkdown12.7 KB
docs/plugins/solid.mdxmarkdown7.0 KB
docs/reference/color-matrix.mdxmarkdown3.8 KB
docs/reference/env-vars.mdxmarkdown6.5 KB
docs/reference/native-span-feed.mdxmarkdown6.0 KB
docs/reference/package-entrypoints.mdxmarkdown9.6 KB
docs/reference/qr-encoder.mdxmarkdown12.3 KB
docs/reference/ssh.mdxmarkdown14.8 KB
docs/reference/standalone-executables.mdxmarkdown7.1 KB
docs/reference/three.mdxmarkdown14.8 KB
docs/reference/tree-sitter.mdxmarkdown4.6 KB

docs/components/scrollbox.mdx

View on GitHub
---
title: ScrollBox
description: A scrollable container component with customizable scrollbars
order: 7
---

# ScrollBox

A scrollable container that supports horizontal and vertical scrolling, sticky scroll behavior, viewport culling, and customizable scrollbars.

## Basic usage

### Renderable api

```typescript
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)
```

### Construct API

```typescript
import { ScrollBox, Box, Text, createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer()

renderer.root.add(
  ScrollBox(
    {
      width: 40,
      height: 20,
    },
    ...Array.from({ length: 100 }, (_, i) =>
      Box(
        { width: "100%", padding: 1, backgroundColor: i % 2 === 0 ? "#292e42" : "#2f3449" },
        Text({ content: `Item ${i}` }),
      ),
    ),
  ),
)
```

## Sticky scroll

Enable sticky scroll to keep content pinned to an edge as new content arrives. Useful for log viewers or chat interfaces.

```typescript
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 bottom (default for chat/logs)
- `"top"` - Stay scrolled to top
- `"left"` - Stay scrolled to left
- `"right"` - Stay scrolled to 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:

```typescript
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 for better performance with large content. When enabled, ScrollBox renders only visible children:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
// 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:

```typescript
// Scroll to top
scrollbox.scrollTo(0)

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

### 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; otherwise it scrolls to reveal the nearest edge.

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

Use it when you focus an element offscreen (search results, a newly inserted form field, etc.) and want to bring it into view without moving the scroll position more than needed.

## Keyboard navigation

When focused, ScrollBox responds to keyboard input:

- **Arrow keys** - Scroll by line
- **Page Up/Down** - Scroll by page
- **Home/End** - Scroll to start/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:

```typescript
scrollbox.wrapper // BoxRenderable - outer wrapper
scrollbox.viewport // BoxRenderable - visible area
scrollbox.content // ContentRenderable - holds children
scrollbox.horizontalScrollBar // ScrollBarRenderable
scrollbox.verticalScrollBar // ScrollBarRenderable
```
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall