📦 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
• Width and 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.3"

For maximum performance, enable caching features:

[dependencies]

boxen = { version = "0.3", 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();

---

🎨 Border Styles

Boxen supports various border styles:

---

🌈 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));

// 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
• 📗 Usage Guide - Detailed usage examples
• 📙 Customization Guide - Advanced styling techniques
• 📕 Performance Guide - Optimization strategies
• 📔 Migration Guide - Upgrading from v0.1.x

Examples

Run the included examples to see boxen in action:

# Basic usage patterns

cargo run --example main_api_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