{"id":12897,"library":"blessed-contrib","title":"Terminal Dashboard Widgets for Blessed","description":"blessed-contrib is a JavaScript library designed for creating rich terminal dashboards and other console-based applications using ASCII/ANSI art. It extends the core `blessed` library, providing a suite of custom widgets such as line charts, bar charts, gauges, LCD displays, tables, and maps, some of which leverage `node-drawille` for advanced graphics. The current stable version is 4.11.0, with releases occurring irregularly, typically annually or semi-annually, focusing on stability. Its key differentiators include a comprehensive set of data visualization widgets tailored for the terminal, seamless integration with `blessed`'s powerful screen management, and explicit support across Linux, OS X, and Windows (with specific prerequisites for the latter). It aims to provide developer-friendly tools for creating visually engaging command-line interfaces.","status":"maintenance","version":"4.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/yaronn/blessed-contrib","tags":["javascript","typescript"],"install":[{"cmd":"npm install blessed-contrib","lang":"bash","label":"npm"},{"cmd":"yarn add blessed-contrib","lang":"bash","label":"yarn"},{"cmd":"pnpm add blessed-contrib","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core terminal UI toolkit that blessed-contrib extends. While listed as a direct dependency in package.json, the documentation explicitly instructs users to install it separately.","package":"blessed","optional":false}],"imports":[{"note":"blessed-contrib is primarily a CommonJS module. For modern TypeScript or ESM-only projects, `import * as contrib from 'blessed-contrib';` is often used, potentially requiring `esModuleInterop: true` in tsconfig or specific Node.js loader configuration.","wrong":"import contrib from 'blessed-contrib';","symbol":"contrib","correct":"const contrib = require('blessed-contrib');"},{"note":"Widget constructors (e.g., `line`, `bar`, `gauge`) are properties of the main `contrib` object, not top-level named exports of the package.","wrong":"import { line } from 'blessed-contrib';","symbol":"Widget Constructors","correct":"const lineWidget = contrib.line({ /* options */ });"},{"note":"An instance of `blessed`'s `screen` is fundamental for all `blessed-contrib` widgets. `blessed` itself is also a CommonJS package and requires the `require()` syntax.","wrong":"import { screen } from 'blessed';","symbol":"blessed.screen()","correct":"const blessed = require('blessed');\nconst screen = blessed.screen();"}],"quickstart":{"code":"import blessed from 'blessed';\nimport contrib from 'blessed-contrib';\n\nconst screen = blessed.screen({\n  smartCSR: true,\n  title: 'blessed-contrib Demo'\n});\n\nconst grid = new contrib.grid({ rows: 12, cols: 12, screen: screen });\n\nconst line = grid.set(0, 0, 6, 6, contrib.line, {\n  style: {\n    line: 'yellow',\n    text: 'green',\n    baseline: 'black'\n  },\n  xLabelPadding: 3,\n  xPadding: 5,\n  label: 'CPU Usage',\n  showLegend: true\n});\n\nconst data = {\n  x: ['t1', 't2', 't3', 't4', 't5'],\n  y: [5, 1, 7, 5, 9]\n};\n\nconst data2 = {\n  x: ['t1', 't2', 't3', 't4', 't5'],\n  y: [2, 8, 4, 6, 3]\n};\n\nline.setData([data, data2]);\n\nconst bar = grid.set(0, 6, 6, 6, contrib.bar, {\n  label: 'Process Memory (MB)',\n  barWidth: 4,\n  barSpacing: 6,\n  xOffset: 0,\n  maxHeight: 100\n});\n\nbar.setData({\n  titles: ['Proc A', 'Proc B', 'Proc C'],\n  data: [85, 40, 65]\n});\n\nscreen.key(['escape', 'q', 'C-c'], function(ch, key) {\n  return process.exit(0);\n});\n\nscreen.render();\n","lang":"typescript","description":"This example sets up a `blessed` screen, uses `blessed-contrib`'s grid layout, and displays a line chart and a bar chart with sample data. It also includes essential keybindings for graceful exit."},"warnings":[{"fix":"For CJS environments: `const contrib = require('blessed-contrib');`. For TypeScript/ESM projects, use `import * as contrib from 'blessed-contrib';` and ensure `esModuleInterop` is enabled in your `tsconfig.json`.","message":"blessed-contrib is primarily a CommonJS module. While TypeScript types are provided, direct ESM `import` statements may require specific `tsconfig` settings (`esModuleInterop: true`) or Node.js loader configurations to function correctly at runtime. The common pattern remains `require()`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always call `screen.append(widget)` or `grid.set(...)` before any `widget.setData()` calls. E.g., `screen.append(line); line.setData([...]);`","message":"Widgets must be appended to a `blessed` screen or a `blessed-contrib` grid instance BEFORE attempting to set their data. Failing to do so can lead to unexpected rendering issues or errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the blessed-contrib documentation or linked resources for Windows setup instructions, typically involving installation of a robust terminal emulator or Git Bash.","message":"For Windows environments, specific prerequisites (like 'Git for Windows' for a proper terminal emulator) are required to run `blessed-contrib` applications correctly. Without these, rendering may be broken or the application may fail to launch.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Maintain regular updates to the latest minor/patch versions. Always test against new major versions of `blessed` as `blessed-contrib` is tightly coupled.","message":"No significant breaking changes or security vulnerabilities specific to blessed-contrib have been widely reported or highlighted in recent versions (4.x) based on available documentation. Major API changes are infrequent.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"If running in an ESM environment, use `import * as contrib from 'blessed-contrib';` or ensure your build system/Node.js setup correctly transpiles or handles CommonJS interop. Alternatively, ensure your file is treated as CommonJS (e.g., `.cjs` extension or `\"type\": \"commonjs\"` in package.json).","cause":"Attempting to use `require()` in an ES Module context without proper configuration.","error":"ReferenceError: require is not defined"},{"fix":"Verify that `const contrib = require('blessed-contrib');` executed successfully and that the `blessed-contrib` package is installed. Ensure no typos in the `contrib` variable name.","cause":"The `contrib` object was not correctly imported or is `undefined` when attempting to access a widget constructor like `contrib.line`.","error":"TypeError: Cannot read properties of undefined (reading 'line')"},{"fix":"Ensure `screen.append(widget)` or `grid.set(...)` is called for the widget instance before any subsequent calls to `widget.setData()` or other methods that require it to be rendered.","cause":"A widget's `setData()` method was called before the widget was added to a `blessed` screen or a `blessed-contrib` grid.","error":"Error: blessed-contrib widgets must be appended to a blessed screen first."},{"fix":"Always call `screen.render()` at the end of your setup to draw the UI. Implement `screen.key(['escape', 'q', 'C-c'], () => process.exit(0));` or similar to keep the application running until a specific exit command.","cause":"The `screen.render()` method was not called, or no `screen.key()` handler was implemented to prevent immediate process exit.","error":"Application starts but shows a blank screen or immediately exits."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}