Console / terminal GUI toolkit for Crystal.

Build Status Version License


Crysterm is a console/terminal toolkit for Crystal. IT IS IN ACTIVE DEVELOPMENT.

The usage and API are DOM-like, and anyone can make awesome terminal applications with Crysterm quickly.

For a quick start, see directory examples/ and consult the User Manual below.

Crysterm is heavily inspired by the terminal library "blessed" for Node.js and, for convenience, shares much of its user-visible API.

Installation and Hello, World!

If you have an existing project and want to add Crysterm to it:

  1. Add the dependency to shard.yml:
    github: crystallabs/crysterm
  1. Run shards

If you just want to try it out by running example programs:

  1. Clone the Crysterm Git repository

  2. Run 'crystal spec' to run all the specs

  3. Run examples from the directory examples/ (for example, crystal examples/

User Manual

Event model

Event model is at the very core of the Crysterm library.

The basic class Event and system's built-in events come from the event_handler shard.

The necessary additional events used by built-in widgets are defined in src/

The final event module (mixin) named EventHandler also comes from the event_handler shard. It provides all the macros and functions needed for a class to be event-enabled, that is, to accept event handlers and emit events. Every class that wants to emit its events needs to include EventHandler.

For more information about the event model, please see

Class hierarchy

Class Event represents the parent class of all events.

Module EventHandler adds methods for adding and removing event handlers, and emitting events.

Basic crysterm class Node includes EventHandler.

Class Screen (of which there can be multiple in a running application) inherits from Node.

Class Element inherits from Node.

All other widgets, including layouts, inherit from Element or some of its subclasses such as Box or List.


Crysterm does not use ncurses. It uses its own functionality to detect term characteristics, parse terminfo, and configure the program to output correct escape sequences for the current terminal. It is arguably as accurate as ncurses, and more optimized in some ways.

The renderer makes use of CSR (change-scroll-region) and BCE (back-color-erase). It draws the screen using the painter's algorithm, with smart cursor movements and screen damage buffer. Only the change (damage) is updated on the screen.

Text Attributes

Generally speaking, to define foreground and background colors and attributes for strings, one can embed appropriate escape sequences into the strings themselves or use Crystal's Colorize module.

Crysterm is interoperable with those two approaches, but also implements its own concept of "tags" in strings, such as "{lightblue-fg} text in light blue {/lightblue-fg}". Tags can be embedded in strings directly, applied from a Hash with generate_tags, and removed from a string with strip_tags or clean_tags. Any existing strings where "{}" should not be interpreted can be protected with escape_tags.


There are three parallel goals:

  1. Add basic functions which do not have many dependencies and which can be implemented and tested standalone.

  2. Implement event model and most basic widgets that will initialize an empty screen:

  • Implement event model
  • Implement Node
  • Implement Screen, a subclass of Node (half-done)
  • Implement Element, a subclass of Node
  • Implement other widgets, subclasses of Element
  1. Add lower-level elements like event loop, event stream parser, terminfo/termcap functions, etc.


Run crystal spec as usual.


Run crystal docs as usual.


  • All the fine folks on FreeNode IRC channel #crystal-lang and on Crystal's Gitter channel

  • Blacksmoke16 for a workable event implementation

  • Asterite, Absolutejam, and Tenebrousedge for additional discussion

  • Chjj for implementing library "blessed" for Node.js

Other projects

List of interesting or similar projects in no particular order:





github statistic
  • 14
  • 0
  • 0
  • 1
  • 3 months ago
  • October 24, 2019

MIT License

Synced at

Tue, 26 May 2020 21:18:45 GMT