📦 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:

---

🌈 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