Termisu

Termisu is a library that provides a minimalistic API for writing text-based user interfaces in pure Crystal. It offers an abstraction layer over terminal capabilities through cell-based rendering with double buffering, allowing efficient and flicker-free TUI development. The API is intentionally small and focused, making it easy to learn, test, and maintain. Inspired by termbox, Termisu brings similar simplicity and elegance to the Crystal ecosystem.

[!WARNING] Termisu is still in development and is considered unstable. The API is subject to change, and you may encounter bugs or incomplete features. Use it at your own risk, and contribute by reporting issues or suggesting improvements!

Installation

1. Add the dependency to your shard.yml:

dependencies:
  termisu:
    github: omarluq/termisu

2. Run shards install

Usage

require "termisu"

termisu = Termisu.new

begin
  # Set individual cells with colors and attributes
  termisu.set_cell(0, 0, 'H', fg: Termisu::Color::Red, attr: Termisu::Attribute::Bold)
  termisu.set_cell(1, 0, 'i', fg: Termisu::Color::Green)

  # Position and show cursor
  termisu.set_cursor(3, 0)

  # Flush renders only changed cells (diff-based)
  termisu.flush

  # Wait for input
  if termisu.wait_for_input(5000)
    byte = termisu.read_byte
  end
ensure
  termisu.close
end

See examples/demo.cr for a complete demonstration.

Roadmap

Current Status: Alpha

Completed

• Terminal I/O primitives (raw mode, alternate screen)
• Terminfo database parser with builtin fallbacks
• Cell-based rendering with double buffering
• Color support (8 basic ANSI colors)
• Text attributes (bold, underline, blink, reverse)
• Cursor control (position, visibility)
• Input reading (bytes, with timeout)
• 256-color and RGB support

In Progress

• Mouse input handling
• Event system (keyboard, mouse, resize)

Planned

• Higher-level widgets and layout system (Maybe)
• Performance optimizations

Inspiration

Termisu is inspired by and follows the design philosophy of:

• nsf/termbox - The original termbox library
• nsf/termbox-go - Go implementation of termbox

Contributing

1. Fork it (https://github.com/omarluq/termisu/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• omarluq - creator and maintainer

License

The gem is available as open source under the terms of the MIT License.

Code of conduct

Everyone interacting in this project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.