DOCSEARCHbyAlgolia
Submit Docs

blessed-contrib

repository·master·Indexed 12 days ago

https://github.com/yaronn/blessed-contrib

A JavaScript library for building terminal dashboards and applications using ASCII/ANSI art. It extends the blessed library with specialized widgets including line, bar, and donut charts, gauges, maps, LCD displays, interactive tables, and tree views. It also provides layout components like Grid and Carousel for organizing widgets on the screen.

Tokens
12.6K
Snippets
48
Records
54
Agent score
96%

What's inside blessed-contrib

  1. Use a Carousel Layout

    master

    A contrib.carousel switches between different views (pages) based on a time interval or keyboard activity. Each page is a function that sets up a view on the screen.

    Options:

    • screen: The blessed screen instance.
    • interval: Time in ms between automatic switches (set to 0 to disable auto-switch).
    • controlKeys: If true, left/right arrow keys control rotation.
        var blessed = require('blessed')
      , contrib = require('./')
      , screen = blessed.screen()

    function page1(screen) {
       var map = contrib.map()
       screen.append(map)
    }

    function page2(screen) {
       var line = contrib.line({ width: 80, height: 30, label: 'Title' })
       screen.append(line)
       line.setData([{ title: 'us-east', x: ['t1', 't2'], y: [0, 2] }])
    }

    var carousel = new contrib.carousel( [page1, page2], {
        screen: screen,
        interval: 3000,
        controlKeys: true
    })
    carousel.start()

  2. Use a Grid Layout

    master

    A contrib.grid allows you to auto-position widgets in a grid. Instead of creating widgets manually, you use grid.set() to specify which widget to create, its position, and its dimensions.

    grid.set(row, col, rowSpan, colSpan, widgetConstructor, options)

       var screen = blessed.screen()
   var grid = new contrib.grid({rows: 12, cols: 12, screen: screen})

   // grid.set(row, col, rowSpan, colSpan, obj, opts)
   var map = grid.set(0, 0, 4, 4, contrib.map, {label: 'World Map'})
   var box = grid.set(4, 4, 4, 4, blessed.box, {content: 'My Box'})

   screen.render()

  4. Run the blessed-contrib demo

    master

    To run the official dashboard demo, clone the repository, install dependencies, and execute the example script.

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

  6. Basic usage of blessed-contrib widgets

    master

    To use blessed-contrib widgets, require both blessed and blessed-contrib. Create a screen using blessed.screen(), initialize a widget using a contrib method, and append the widget to the screen.

    Important: You must call screen.append(widget) before calling widget.setData().

    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();

  7. Fix encoding or missing character issues

    master

    If your terminal displays question marks or missing characters, it is likely an encoding or terminal compatibility issue. Try running your script with the LANG and TERM environment variables set to ensure UTF-8 and 256-color support.

    $> LANG=en_US.utf8 TERM=xterm-256color node your-code.js

  8. Create a simple dashboard using grids and widgets

    master

    You can build a dashboard by creating a blessed.screen(), initializing a contrib.grid, and using grid.set() to place widgets like contrib.line or contrib.map into specific grid cells.

    To update data in a widget (e.g., a line chart), use the .setData() method with an object containing x and y arrays.

    var blessed = require('blessed')
  , contrib = require('blessed-contrib')
  , screen = blessed.screen()
  , grid = new contrib.grid({rows: 1, cols: 2, screen: screen})

var line = grid.set(0, 0, 1, 1, contrib.line,
  {
    style: {
      line: "yellow"
     , text: "green"
     , baseline: "black"
    }
   , xLabelPadding: 3
   , xPadding: 5
   , label: 'Stocks'
  })

var map = grid.set(0, 1, 1, 1, contrib.map, {label: 'Servers Location'})

var lineData = {
   x: ['t1', 't2', 't3', 't4'],
   y: [5, 1, 7, 5]
}

line.setData([lineData])

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

screen.render()

  9. Use an LCD Display

    master

    Use contrib.lcd() to create a digital-style display. You can update the content using lcd.setDisplay(string) and modify configuration at runtime using lcd.setOptions(options).

       var lcd = contrib.lcd(
     { segmentWidth: 0.06 
     , segmentInterval: 0.11 
     , strokeWidth: 0.11 
     , elements: 4 
     , display: 321 
     , elementSpacing: 4 
     , elementPadding: 2 
     , color: 'white' 
     , label: 'Storage Remaining'})

	lcd.setDisplay(23 + 'G');
	lcd.setOptions({});

  11. Use a Map with Markers

    master

    Use contrib.map() to render a map. You can add markers to the map using the addMarker method, providing longitude (lon), latitude (lat), color, and a character (char) to represent the marker.

       var map = contrib.map({label: 'World Map'})
   map.addMarker({"lon" : "-79.0000", "lat" : "37.5000", color: "red", char: "X" })

  12. Create an Interactive Table

    master

    Use contrib.table() to create a data table.

    Interactivity: If interactive: true is set, you can call table.focus() to allow keyboard navigation. Use setData({ headers, data }) to populate it.

       var table = contrib.table(
     { keys: true
     , fg: 'white'
     , selectedFg: 'white'
     , selectedBg: 'blue'
     , interactive: true
     , label: 'Active Processes'
     , width: '30%'
     , height: '30%'
     , border: {type: "line", fg: "cyan"}
     , columnSpacing: 10
     , columnWidth: [16, 12, 12] })

   table.focus()
   table.setData({
     headers: ['col1', 'col2', 'col3']
   , data: [ [1, 2, 3], [4, 5, 6] ]
   })