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

Add the dependency to your shard.yml:

dependencies:
  termisu:
    github: omarluq/termisu

Run shards install

Usage

require "termisu"

termisu = Termisu.new

begin
  # Set 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)
  termisu.set_cursor(2, 0)
  termisu.render

  # Event loop with keyboard and mouse support
  termisu.enable_mouse
  loop do
    if event = termisu.poll_event(100)
      case event
      when Termisu::Events::Key
        break if event.key.escape?
        break if event.key.lower_q?
      when Termisu::Events::Mouse
        termisu.set_cell(event.x, event.y, '*', fg: Termisu::Color.cyan)
        termisu.render
      end
    end
  end
ensure
  termisu.close
end

See examples/showcase.cr and examples/keyboard_and_mouse.cr for complete demonstrations.

Termisu Showcase

Roadmap

Current Status: Alpha (v0.1.0)

| Component | Status | |-----------|--------| | Terminal I/O | ✅ Complete | | Terminfo | ✅ Complete | | Double Buffering | ✅ Complete | | Colors | ✅ Complete | | Attributes | ✅ Complete | | Keyboard Input | ✅ Complete | | Mouse Input | ✅ Complete | | Event System | ✅ Complete | | Async Channels | 🔄 Planned (v0.2) | | Resize Events | 🔄 Planned (v0.2) | | Unicode/Wide Chars | 🔄 Planned (v0.2) |

Completed

Terminal I/O - Raw mode, alternate screen, EINTR handling
Terminfo - Binary parser (16/32-bit), 414 capabilities, builtin fallbacks
Double Buffering - Diff-based rendering, cell batching, state caching
Colors - ANSI-8, ANSI-256, RGB/TrueColor with conversions
Attributes - Bold, underline, blink, reverse, dim, italic, hidden
Keyboard Input - 170+ keys, F1-F24, modifiers (Ctrl/Alt/Shift/Meta)
Mouse Input - SGR (mode 1006), normal (mode 1000), motion events
Event System - Unified Key/Mouse events, Kitty protocol, modifyOtherKeys
Performance - RenderState optimization, escape sequence batching
Terminfo tparm - Full processor with conditionals, stack, variables
Logging - Structured async/sync dispatch, zero hot-path overhead

Planned (v0.2.0) - Async Architecture

Async event channels - Crystal fiber/channel-based event system
SIGWINCH resize events - Channel-based resize notification
Unicode/wide character support - CJK, emoji (wcwidth)
Synchronized updates - DEC mode 2026 (prevents screen tearing)

Future (v0.3.0+)

Async input reader fiber
Timer/tick channels for animations
Fan-in event multiplexer
Strikethrough attribute

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

See CONTRIBUTING.md for detailed guidelines.

Fork it (https://github.com/omarluq/termisu/fork)
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
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.

CrystalDoc.info

termisu