Home

Awesome

<h1 align="center"><img width="440" src="docs/crossterm_full.png" /></h1>

Donate Travis Latest Version MIT docs Lines of Code Join us on Discord

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).

Table of Contents

Features

<!-- WARNING: Do not change following heading title as it's used in the URL by other crates! -->

Tested Terminals

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.

<details> <summary> Click to show Cargo.toml. </summary> 
[dependencies]
crossterm = "0.27"
</details> <p></p> 
use std::io::{stdout, Write};

use crossterm::{
    execute,
    style::{Color, Print, ResetColor, SetBackgroundColor, SetForegroundColor},
    ExecutableCommand,
    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.27"
features = ["event-stream"]
FeatureDescription
event-streamfutures::Stream producing Result<Event>.
serde(De)serializing of events.
eventsReading input/system events (enabled by default)
filedescriptorUse raw filedescriptor for all events rather then mio dependency

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

Dependency Justification

DependencyUsed forIncluded
bitflagsKeyModifiers, those are differ based on input.always
parking_lotlocking RwLocks with a timeout, const mutexes.always
libcUNIX terminal_size/raw modes/set_title and several other low level functionality.optional (events feature), UNIX only
Mioevent readiness polling, waking up polleroptional (events feature), UNIX only
signal-hooksignal-hook is used to handle terminal resize SIGNAL with Mio.optional (events feature),UNIX only
winapiUsed for low-level windows system calls which ANSI codes can't replacewindows only
futures-coreFor async stream of eventsonly with event-stream feature flag
serdeserializing and deserializing of eventsonly 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

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.