Cross-platform Terminal Manipulation Library

Have you ever been disappointed when a terminal library for the Rust language was only written for UNIX systems? Crossterm provides clearing, input handling, styling, cursor movement and terminal actions for both Windows and UNIX systems.

Crossterm aims to be simple and easy to call in code. Through the simplicity of Crossterm, you do not have to worry about the platform you are working with.

This crate 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
  • Tested Terminals
• Getting Started
  • Feature Flags
  • crossterm vs crossterm_* crates
• Other Resources
• Used By
• Contributing

Features

• Cross-platform
• Multi-threaded (send, sync)
• Detailed documentation
• Few dependencies
• Cursor (feature cursor)
  • Move the cursor N times (up, down, left, right)
  • 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 (feature style)
  • 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 (feature 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
• Input (feature input)
  • Read character
  • Read line
  • Read key input events (async / sync)
  • Read mouse input events (press, release, position, button)
• Screen (feature screen)
  • Alternate screen
  • Raw screen

Tested Terminals

• Windows Powershell
  • Windows 10 (Pro)
• Windows CMD
  • Windows 10 (Pro)
  • Windows 8.1 (N)
• Ubuntu Desktop Terminal
  • Ubuntu 17.10
• (Arch, Manjaro) KDE Konsole
• Linux Mint

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

Click to show Cargo.toml.

[dependencies]
crossterm = "0.11"

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

use crossterm::{execute, Attribute, Color, Output, ResetColor, Result, SetBg, SetFg};

fn main() -> Result<()> {
    execute!(
        stdout(),
        // Blue foreground
        SetFg(Color::Blue),
        // Red background
        SetBg(Color::Red),
        Output("Styled text here.".to_string()),
        // Reset to default colors
        ResetColor
    )
}

Feature Flags

All features are enabled by default. You can disable default features and enable some of them only.

[dependencies.crossterm]
version = "0.11"
default-features = false        # Disable default features
features = ["cursor", "screen"] # Enable required features only

Feature	Description	Links
input	Sync/Async input readers	API documentation, crates.io, GitHub
cursor	Cursor manipulation	API documentation, crates.io, GitHub
screen	Alternate screen & raw mode	API documentation, crates.io, GitHub
terminal	Size, clear, scroll	API documentation, crates.io, GitHub
style	Colors, text attributes	API documentation, crates.io, GitHub

crossterm vs crossterm_* crates

There're two ways how to use the Crossterm library:

• crossterm crate with the cursor feature flag,
• crossterm_cursor crate.

Both provide same functionality, the only difference is the namespace (crossterm vs crossterm_cursor).

The first way (crossterm crate with feature flags) is preferred. The second way will be deprecated and no longer supported soon. The crossterm_* crates will be marked as deprecated and repositories archived on the GitHub. See the Merge sub-crates to the crossterm crate for more details.

crossterm crate:

[dependencies.crossterm]
version = "0.11"
default-features = false        # Disable default features
features = ["cursor"]           # Enable cursor feature only

use crossterm::cursor;

crossterm_curosr crate:

[dependencies]
crossterm_cursor = "0.3"

use crossterm_cursor::cursor;

Other Resources

• API documentation
• Examples repository

Used By

• Broot
• Cursive
• TUI
• Rust-sloth

Contributing

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

Authors

• Timon Post - Project Owner & creator

Support

Would you like Crossterm to be even more gorgeous and beautiful? You can help with this by donating.

License

This project, crossterm and all it's 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.