Guide · Open source

How to use blessed-contrib: install and build terminal dashboards

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

blessed-contrib is a JavaScript library that extends the blessed terminal UI toolkit with extra widgets such as line charts, bar charts, maps, gauges, donuts, logs and tables. This guide shows how to install it, create a screen, and add widgets that display data inside a text terminal, including over SSH. It is written for developers comfortable with Node.js who want a visual status readout without a browser.

blessed-contribyaronn/blessed-contrib · ★ 15.8k · MIT Install options & downloads

Quick start

1Check prerequisites. Install the latest stable Node.js LTS and npm. On Windows, follow the prerequisites linked in the README.
2Install the packages. Run npm install blessed blessed-contrib in your project folder.
3Create a screen. Require blessed and blessed-contrib, then call blessed.screen().
4Add a widget. Create a contrib widget with options such as label, then call screen.append on it before setting data.
5Set data. Call the widget's setData method, such as line.setData([data]) for a line chart.
6Render and exit keys. Bind keys such as q or Ctrl-C to process.exit, then call screen.render().

What blessed-contrib is and who it suits

blessed-contrib builds on blessed and adds widgets drawn with ASCII and ANSI art, including drawille-based charts. Its output is text in a terminal, so it runs anywhere a terminal does, including remote servers reached over SSH.

It is a library, not a ready-made dashboard. You write JavaScript against it to decide what each widget shows. If you need graphical browser charts, this is the wrong tool.

Good fit: monitoring or status dashboards in a terminal, and remote servers over SSH.
Good fit: developers already working with blessed or terminal UI code.
Not a fit: people who want a dashboard with no coding, or browser-based graphical charts.

Install blessed-contrib with npm

Use the latest stable version of Node.js LTS. Install blessed-contrib together with its peer dependency blessed in one command.

The README also covers running the bundled demo, which needs a git clone and npm install. Windows users should follow the prerequisites linked in the README before running dashboards there.

npm install blessed blessed-contrib

Every blessed-contrib app starts with a blessed screen. You create a widget with a contrib function, append it to the screen, and then pass it data. The README notes that you must append a widget before setting its data.

Finish by calling screen.render(). The example also binds the escape, q and Ctrl-C keys to exit the process.

Require blessed and blessed-contrib.
Create the screen with blessed.screen().
Create a widget such as contrib.line with options like label and style.
Call screen.append(widget) before widget.setData(...).
Call screen.render() to draw the screen.

var blessed = require('blessed')
  , contrib = require('blessed-contrib')
  , screen = blessed.screen()
  , line = contrib.line(
      { style: { line: "yellow", text: "green", baseline: "black" }
      , xLabelPadding: 3
      , xPadding: 5
      , label: 'Title' })
  , data = { x: ['t1', 't2', 't3', 't4'], y: [5, 1, 7, 5] }
screen.append(line) //must append before setting data
line.setData([data])

screen.key(['escape', 'q', 'C-c'], function(ch, key) {
  return process.exit(0);
});

screen.render()

The README documents these widgets: line chart, bar chart, stacked bar chart, map, gauge, stacked gauge, donut, LCD display, rolling log, picture, sparkline, table, tree and markdown. Each follows the same pattern of creating, appending and setting data.

Donuts take an array of objects with percent and label, and color is optional and defaults to green. Gauges use setPercent for a single value or setStack for stacked portions. Logs take new lines through log.log(...).

Line chart: setData takes an array of series with title, x and y.
Bar chart: setData takes titles and data arrays.
Gauge: setPercent(25) sets one value; setStack([30,30,40]) shows stacked values.
Rolling log: call log.log("new log line") to add a line.
Picture: the README says only png images are supported.

donut.setData([
  {percent: 87, label: 'rcp', 'color': 'green'},
  {percent: 43, label: 'rcp', 'color': 'cyan'},
]);

Update widgets and run the demo

Call a widget's setData method again whenever new values arrive, then call screen.render() so the terminal shows the change. The README says the donut resizes to fit added data, but you are still limited by the screen space available.

To see working code, clone the repository and run the bundled dashboard example. The README links the example source at examples/dashboard.js.

Check examples/line-fraction.js, examples/multi-line-chart.js and examples/donut.js for specific widgets.
The README points to examples/lcd.js for adjusting LCD segment settings at runtime.

git clone https://github.com/yaronn/blessed-contrib.git
cd blessed-contrib
npm install
node ./examples/dashboard.js

What people use it for

A status screen for a server that you check over SSH.
A terminal gauge or donut showing resource usage on a remote machine.
A rolling log panel that displays new lines as your program produces them.
A table or tree that lays out structured data in a terminal window.

Frequently asked questions

Is blessed-contrib free to use?

blessed-contrib is released under the MIT licence, as shown in the project listing. You can use it in your own projects under that licence.

What do I need to install blessed-contrib?

The README asks for the latest stable version of Node.js LTS and npm. You install blessed-contrib with blessed as a peer dependency using npm install blessed blessed-contrib.

Does blessed-contrib work on Windows?

The README says it works on Linux, OS X and Windows. For Windows it links a set of prerequisites that you should follow before running dashboards.

Can I use blessed-contrib over SSH?

Yes. The project describes itself as friendly to terminals and ssh, because its output is text drawn in a terminal rather than a browser page.

Do I need to write code to use blessed-contrib?

Yes. It is a library you code against, so it does not provide a dashboard you can configure without programming.

What are the alternatives to blessed-contrib?

The project lists blessed, ink, and similar terminal dashboard tools such as gotop as comparable options. blessed is the base toolkit that blessed-contrib extends.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use blessed-contrib if you are a Node.js developer who wants a terminal dashboard you control in code, including on remote servers over SSH. Pick something else if you want a dashboard with no coding, or graphical charts in a browser.

Install options & downloads