Cross-platform Terminal Manipulation Library

Crossterm is a pure-rust, terminal manipulation library that makes it possible to write cross-platform text-based interfaces (see features). It supports all UNIX and Windows terminals down to Windows 7 (not all terminals are tested, see Tested Terminals for more info).

Cross-platform Terminal Manipulation Library

Features

Cross-platform
Multi-threaded (send, sync)
Detailed documentation
Few dependencies
Full control over writing and flushing output buffer
Is tty
Cursor
- Move the cursor N times (up, down, left, right)
- Move to previous / next line
- Move to column
- Set/get the cursor position
- Store the cursor position and restore to it later
- Hide/show the cursor
- Enable/disable cursor blinking (not all terminals do support this feature)
Styled output
- Foreground color (16 base colors)
- Background color (16 base colors)
- 256 (ANSI) color support (Windows 10 and UNIX only)
- RGB color support (Windows 10 and UNIX only)
- Text attributes like bold, italic, underscore, crossed, etc
Terminal
- Clear (all lines, current line, from cursor down and up, until new line)
- Scroll up, down
- Set/get the terminal size
- Exit current process
- Alternate screen
- Raw screen
- Set terminal title
- Enable/disable line wrapping
Event
- Input Events
- Mouse Events (press, release, position, button, drag)
- Terminal Resize Events
- Advanced modifier (SHIFT | ALT | CTRL) support for both mouse and key events and
- futures Stream (feature 'event-stream')
- Poll/read API

Tested Terminals

Console Host
- Windows 10 (Pro)
- Windows 8.1 (N)
Ubuntu Desktop Terminal
- Ubuntu 17.10
- Pop!_OS ( Ubuntu ) 20.04
(Arch, Manjaro) KDE Konsole
(Arch, NixOS) Kitty
Linux Mint
(OpenSuse) Alacritty
(Chrome OS) Crostini

This crate supports all UNIX terminals and Windows terminals down to Windows 7; however, not all of the terminals have been tested. If you have used this library for a terminal other than the above list without issues, then feel free to add it to the above list - I really would appreciate it!

Getting Started

see the examples directory and documentation for more advanced examples.

Click to show Cargo.toml.

[dependencies]
crossterm = "0.26"

use std::io::{stdout, Write};

use crossterm::{
    execute,
    style::{Color, Print, ResetColor, SetBackgroundColor, SetForegroundColor},
    ExecutableCommand, Result,
    event,
};

fn main() -> std::io::Result<()> {
    // using the macro
    execute!(
        stdout(),
        SetForegroundColor(Color::Blue),
        SetBackgroundColor(Color::Red),
        Print("Styled text here."),
        ResetColor
    )?;

    // or using functions
    stdout()
        .execute(SetForegroundColor(Color::Blue))?
        .execute(SetBackgroundColor(Color::Red))?
        .execute(Print("Styled text here."))?
        .execute(ResetColor)?;
    
    Ok(())
}

Checkout this list with all possible commands.

Feature Flags

[dependencies.crossterm]
version = "0.26"
features = ["event-stream"]

Feature	Description
`event-stream`	`futures::Stream` producing `Result<Event>`.
`serde`	(De)serializing of events.
`events`	Reading input/system events (enabled by default)
`filedescriptor`	Use raw filedescriptor for all events rather then mio dependency

To use crossterm as a very tin layer you can disable the events feature or use filedescriptor feature. This can disable mio / signal-hook / signal-hook-mio dependencies.

Dependency Justification

Dependency	Used for	Included
`bitflags`	`KeyModifiers`, those are differ based on input.	always
`parking_lot`	locking `RwLock`s with a timeout, const mutexes.	always
`libc`	UNIX terminal_size/raw modes/set_title and several other low level functionality.	optional (`events` feature), UNIX only
`Mio`	event readiness polling, waking up poller	optional (`events` feature), UNIX only
`signal-hook`	signal-hook is used to handle terminal resize SIGNAL with Mio.	optional (`events` feature),UNIX only
`winapi`	Used for low-level windows system calls which ANSI codes can't replace	windows only
`futures-core`	For async stream of events	only with `event-stream` feature flag
`serde`	serializing and deserializing of events	only with `serde` feature flag

Other Resources

Used By

Contributing

We highly appreciate when anyone contributes to this crate. Before you do, please, read the Contributing guidelines.

Authors

Timon Post - Project Owner & creator

License

This project, crossterm and all its sub-crates: crossterm_screen, crossterm_cursor, crossterm_style, crossterm_input, crossterm_terminal, crossterm_winapi, crossterm_utils are licensed under the MIT License - see the LICENSE file for details.

martinvonz/crossterm