crossterm — Cross-Platform Terminal Manipulation Library for Rust

Introduction

crossterm is a pure Rust library that provides cross-platform terminal manipulation capabilities. It offers a single API for cursor control, text styling, input event handling, and raw mode across Windows (including legacy cmd.exe), macOS, and Linux terminals. It is the low-level foundation used by popular Rust TUI frameworks like Ratatui.

What crossterm Does

• Controls cursor position, visibility, and shape across all major platforms
• Applies text colors, background colors, bold, italic, underline, and other attributes
• Reads keyboard, mouse, and resize events synchronously or asynchronously
• Manages terminal modes including raw mode and alternate screen buffers
• Provides both command-based (queued) and immediate execution models

Architecture Overview

crossterm abstracts platform-specific terminal APIs behind a unified command interface. On Unix systems it uses ANSI escape sequences written to stdout. On Windows it uses the Console API for legacy terminals and ANSI sequences for Windows Terminal. Commands can be executed immediately with execute!() or queued with queue!() for batch flushing. The event system uses platform-native polling (epoll on Linux, kqueue on macOS, WaitForMultipleObjects on Windows).

Self-Hosting & Configuration

• Add crossterm as a dependency in Cargo.toml
• No C dependencies or build scripts; compiles as pure Rust
• Enable the event-stream feature for async event reading with tokio or async-std
• Use the serde feature to serialize/deserialize events and styles
• Compatible with Rust stable; no nightly features required

Key Features

• Pure Rust with no C bindings or unsafe dependencies
• Works on Windows (cmd.exe and Windows Terminal), macOS, and Linux
• Supports both synchronous and async (tokio/async-std) event streams
• Command pattern with queue!() and execute!() macros for efficient output
• Foundation library for Ratatui, the most popular Rust TUI framework

Comparison with Similar Tools

• termion — Unix-only Rust terminal library; crossterm adds Windows support
• ncurses/pancurses — C-based curses bindings; crossterm is pure Rust without FFI
• console (Rust) — focused on high-level styling; crossterm provides lower-level terminal control
• tcell (Go) — similar cross-platform terminal library but for the Go ecosystem
• prompt_toolkit (Python) — Python terminal toolkit; crossterm serves the Rust ecosystem

FAQ

Q: Does crossterm work on Windows cmd.exe? A: Yes. It uses the Windows Console API for legacy terminals and ANSI sequences for modern Windows Terminal.

Q: Is crossterm used by Ratatui? A: Yes. Ratatui uses crossterm as its default backend for terminal rendering.

Q: Can I read mouse events? A: Yes. Enable mouse capture with crossterm::event::EnableMouseCapture and read mouse events from the event stream.

Q: Does crossterm support async event handling? A: Yes. Enable the event-stream feature to use EventStream with tokio or async-std.

Sources

• https://github.com/crossterm-rs/crossterm
• https://docs.rs/crossterm