ansi-scrollbox

a basic scrollable area for terminal apps

Install

npm install ansi-scrollbox

Usage

var scrollbox = require('ansi-scrollbox')
var differ = require('ansi-diff')()
var lorem = require('@jamen/lorem')

var box = scrollbox({
  width: 20,
  height: 20
})

box.setContent(lorem(6000))

function render () {
  process.stdout.write(differ.update(box.toString()))
}
setInterval(render, 100)

require('keypress')(process.stdin)
process.stdin.setRawMode(true)
process.stdin.resume()
// Optionally add default scroll keybindings (things like up, down, home, end)
process.stdin.on('keypress', box.keypress)

API

box = scrollbox(opts={})

Prepare a new scrollbox.

• opts.width - Width in columns of the scrollbox.
• opts.height - Height in rows of the scrollbox.

box.setContent(content), box.content = content

Set the content of the scrollbox.

box.content

Get the content of the scrollbox.

box.scroll(offset)

Set the scroll position. offset is the number of rows from the start of the content. When offset is negative, it's the number of rows from the end of the content. Use -1 to scroll to the very end; -1 is "sticky" so it will stay at the end when the content updates.

box.resize(opts)

Update the size of the scrollbox.

• opts.width - Width in columns of the scrollbox.
• opts.height - Height in rows of the scrollbox.

box.toString()

Get the visible contents of the box. Use with something like ansi-diff for efficient updates on screene.

unsub = box.subscribe(listener)

Call listener whenever the box's content, size, or scroll position change. Do unsub() to stop listening.

box.keypress

An event listener that implements basic keyboard controls:

• up or k to scroll 1 row up
• down or j to scroll 1 row down
• home to scroll to the start
• end to scroll to the start

Use it with the keypress module:

require('keypress')(process.stdin)
process.stdin.on('keypress', box.keypress)

License

Apache-2.0

ansi-scrollbox change log

All notable changes to this project will be documented in this file.

This project adheres to Semantic Versioning.

0.2.1

• Update dependencies.
• Add more documentation.

0.2.0

• Calculate all scrolling from the start of the content. Previously scrolling to the end, then back up, would calculate scrolling from the end of the content, so the content would autoscroll as it was updated. Now ansi-scrollbox only autoscrolls if you're at the very bottom.
• Add a subscribe(listener) API to listen for updates to content, size or scroll

0.1.0

• Initial (pretty beta) release.