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