📦 Boxen

Create beautiful boxes in the terminal with Rust

A Rust implementation of the popular boxen library for creating styled terminal boxes around text.

Features • Installation • Quick Start • Examples • Documentation

---

✨ Features

🎨 Styling Multiple border styles (single, double, round, bold, custom) Rich color support (named, hex, RGB) Title support with positioning Dim borders and backgrounds	📐 Layout Flexible text alignment (left, center, right) Precise padding and margins Dynamic width/height with closures Fixed width/height constraints Fullscreen mode
⚡ Performance 30x faster than baseline Thread-local string pooling Optional Unicode width caching Optional terminal size caching	🛡️ Quality Type-safe API with builder pattern Comprehensive error handling Unicode and ANSI aware 100% backward compatible

---

📦 Installation

Add boxen to your Cargo.toml:

[dependencies]
boxen = "0.4"

For maximum performance, enable caching features:

[dependencies]
boxen = { version = "0.4", features = ["width-cache", "terminal-cache"] }

---

🚀 Quick Start

use boxen::{boxen, builder, BorderStyle, TextAlignment};

fn main() {
    // Simple box with default settings
    let simple = boxen("Hello, World!", None).unwrap();
    println!("{}", simple);
    // ┌─────────────┐
    // │Hello, World!│
    // └─────────────┘

    // Styled box with builder pattern
    let fancy = builder()
        .border_style(BorderStyle::Double)
        .padding(2)
        .text_alignment(TextAlignment::Center)
        .title("Greeting")
        .border_color("blue")
        .render("Hello, World!")
        .unwrap();
    println!("{}", fancy);
}

---

📚 Examples

Basic Usage

Code: use boxen::boxen; let result = boxen("Simple box", None) .unwrap(); println!("{}", result);

Output: ┌──────────┐ │Simple box│ └──────────┘

Styled Box

Code: use boxen::{builder, BorderStyle}; let result = builder() .border_style(BorderStyle::Round) .padding(1) .title("Status") .border_color("green") .render("All systems operational") .unwrap();

Output: ╭─── Status ────╮ │ │ │ All systems │ │ operational │ │ │ ╰───────────────╯

Convenience Functions

use boxen::{simple_box, double_box, round_box};

println!("{}", simple_box("Default style"));
println!("{}", double_box("Double border"));
println!("{}", round_box("Round corners"));

Advanced Styling

use boxen::{builder, BorderStyle, TextAlignment, TitleAlignment, Float};

let result = builder()
    .border_style(BorderStyle::Bold)
    .padding((2, 4, 2, 4))  // top, right, bottom, left
    .margin(1)
    .text_alignment(TextAlignment::Center)
    .title_alignment(TitleAlignment::Center)
    .float(Float::Center)
    .width(40)
    .title("🎉 Celebration")
    .border_color("#ff6b6b")
    .background_color("#ffe66d")
    .render("Congratulations!\nYou've mastered boxen!")
    .unwrap();

Dynamic Sizing

Boxen supports both fixed and dynamic width/height using closures that adapt to available terminal space:

use boxen::builder;

// Fixed width (traditional approach)
let result = builder()
    .width(50)
    .render("Fixed width box")
    .unwrap();

// Dynamic width - use 80% of available terminal width
let result = builder()
    .width(|available: usize| (available * 4 / 5).max(30))
    .render("This box adapts to terminal width")
    .unwrap();

// Dynamic height - use 50% of available terminal height
let result = builder()
    .height(|available: usize| (available / 2).max(10))
    .render("Multi\nLine\nContent")
    .unwrap();

// Both dynamic - fully responsive box
let result = builder()
    .width(|available: usize| (available * 3 / 4).max(40))
    .height(|available: usize| (available / 3).max(8))
    .render("Fully responsive box")
    .unwrap();

// Mix fixed and dynamic
let result = builder()
    .width(|available: usize| available.min(60))  // Cap at 60 columns
    .height(15)  // Fixed height
    .render("Dynamic width, fixed height")
    .unwrap();

Key features:

• 🎯 Unified API - Same .width() and .height() methods accept both fixed values and closures
• 📏 Terminal-aware - Closures receive available terminal space as parameter
• 🔄 100% backward compatible - Existing code using .width(50) continues to work
• 🎨 Flexible - Mix fixed and dynamic dimensions as needed

---

🎨 Border Styles

Boxen supports various border styles:

Style	Preview	Description
Single	┌─┐ │ │ └─┘	Clean single-line borders
Double	╔═╗ ║ ║ ╚═╝	Bold double-line borders
Round	╭─╮ │ │ ╰─╯	Smooth rounded corners
Bold	┏━┓ ┃ ┃ ┗━┛	Heavy bold borders
SingleDouble	╓─╖ ║ ║ ╙─╜	Single horizontal, double vertical
DoubleSingle	╒═╕ │ │ ╘═╛	Double horizontal, single vertical
Classic	+--+ | | +--+	ASCII-compatible classic style

---

🌈 Color Support

Boxen supports multiple color formats:

use boxen::builder;

// Named colors (16 standard terminal colors)
builder()
    .border_color("red")
    .background_color("blue");

// Hex colors
builder()
    .border_color("#ff0000")
    .background_color("#0000ff");

// RGB colors
builder()
    .border_color((255, 0, 0))
    .background_color((0, 0, 255));

// Title colors (independent from border color)
builder()
    .title("Status")
    .title_color("green")
    .border_color("blue");

// Dim borders for subtle styling
builder()
    .border_color("cyan")
    .dim_border(true);

Available named colors: black, red, green, yellow, blue, magenta, cyan, white, bright-black, bright-red, bright-green, bright-yellow, bright-blue, bright-magenta, bright-cyan, bright-white

---

⚡ Performance

Boxen is highly optimized for speed and memory efficiency:

Benchmark Results

Operation	Time	vs Baseline
Simple box	1.57μs	30x faster ⚡
Unicode content	2.93μs	40x faster ⚡
Complex styled box	12.2μs	-
Large text (1000 chars)	102.75μs	8x faster ⚡
Batch (100 boxes)	150ms	30x faster ⚡

Core Optimizations

✅ Thread-local string pooling - Reduces allocations by 24-87%
✅ Smart buffer management - Pre-allocated buffers with capacity hints
✅ Efficient ANSI handling - Proper escape sequence processing
✅ Unicode optimization - Fast width calculations

Optional Performance Features

Enable caching for even better performance:

[dependencies]
boxen = { version = "0.3", features = ["width-cache", "terminal-cache"] }

Feature	Benefit	Use Case
width-cache	2-3x faster Unicode	Apps with CJK text, emoji
terminal-cache	10-20% faster batch	Rendering multiple boxes
dhat-heap	Memory profiling	Development & optimization

Performance gains:

• 90% cache hit rates for typical workloads

• Lock-free thread-local caching
• Automatic cache invalidation on terminal resize (Unix)
• Configurable cache sizes and TTL

📖 See Performance Guide for detailed information.

---

🎯 Use Cases

CLI Tools // Success messages println!("{}", simple_box("✓ Build successful!") ); // Error messages println!("{}", builder() .border_color("red") .render("✗ Build failed") .unwrap() );

Status Displays // System status println!("{}", builder() .title("System Status") .border_color("green") .render("All systems operational") .unwrap() );

Notifications // User notifications println!("{}", builder() .title("🔔 Notification") .padding(2) .render("You have 3 new messages") .unwrap() );

---

📖 Documentation

Guides

• 📘 API Documentation - Complete API reference

Examples

Run the included examples to see boxen in action:

# Basic usage patterns
cargo run --example main_api_demo

# Dynamic width/height sizing
cargo run --example dynamic_sizing_demo

# Color demonstrations
cargo run --example color_demo

# Comprehensive feature showcase
cargo run --example comprehensive_demo

# Performance testing
cargo run --example performance_demo

# Caching features demo
cargo run --example caching_demo --features width-cache,terminal-cache

# Memory profiling
cargo run --example memory_profiling --features dhat-heap

# Error handling patterns
cargo run --example error_handling_demo

# Fullscreen mode
cargo run --example fullscreen_demo

# Interactive clock with spinner
cargo run --example clock_spinner

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. 🐛 Report bugs - Open an issue with details
2. 💡 Suggest features - Share your ideas
3. 📝 Improve docs - Help others learn
4. 🔧 Submit PRs - Fix bugs or add features

Please read our Contributing Guide for details.

---

📜 License

This project is licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

---

🙏 Acknowledgments

• Inspired by the original boxen TypeScript library by Sindre Sorhus
• Built with ❤️ for the Rust community
• Thanks to all contributors

---

⬆ back to top

Made with 🦀 Rust • Report Bug • Request Feature