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
|
|
|
|
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"] }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);
}|
Code: use boxen::boxen;
let result = boxen("Simple box", None)
.unwrap();
println!("{}", result); |
Output: |
|
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: |
use boxen::{simple_box, double_box, round_box};
println!("{}", simple_box("Default style"));
println!("{}", double_box("Double border"));
println!("{}", round_box("Round corners"));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();Boxen supports both fixed and dynamic width/height using closures that adapt to available terminal space:
use boxen::builder;
// Fixed width
let fixed = builder()
.width(50)
.render("Fixed width box")
.unwrap();
// Dynamic width - 80% of terminal, minimum 30 columns
let dynamic = builder()
.width(|available| (available * 4 / 5).max(30))
.render("Dynamic width adapts to terminal size")
.unwrap();Transform markdown syntax into beautifully styled terminal output:
|
Code: use boxen::builder;
let markdown = r#"
# Commands
**create** - Create a new item
**delete** - Remove an item
Use `--help` for more info
"#;
let result = builder()
.title("Help")
.markdown() // Enable markdown
.render(markdown)
.unwrap();
println!("{}", result); |
Features:
|
Custom Markdown Styling:
use boxen::{builder, Color, markdown::{MarkdownStyle, LinkStyle, ItalicStyle}};
let style = MarkdownStyle {
h1_color: Color::Named("magenta".to_string()),
bold_color: Some(Color::Named("yellow".to_string())),
link_style: LinkStyle::ShowUrl,
italic_style: ItalicStyle::Underline,
..Default::default()
};
let result = builder()
.markdown_with_style(style)
.render("# Custom **styling** for [links](https://example.com)")
.unwrap();Quick Markdown Box:
use boxen::markdown_box;
// One-line markdown rendering
println!("{}", markdown_box("# Quick\n**Easy** markdown!"));// 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:
<table>
<tr>
<th>Style</th>
<th>Preview</th>
<th>Description</th>
</tr>
<tr>
<td><code>Single</code></td>
<td><pre>โโโ
โ โ
โโโ</pre></td>
<td>Clean single-line borders</td>
</tr>
<tr>
<td><code>Double</code></td>
<td><pre>โโโ
โ โ
โโโ</pre></td>
<td>Bold double-line borders</td>
</tr>
<tr>
<td><code>Round</code></td>
<td><pre>โญโโฎ
โ โ
โฐโโฏ</pre></td>
<td>Smooth rounded corners</td>
</tr>
<tr>
<td><code>Bold</code></td>
<td><pre>โโโ
โ โ
โโโ</pre></td>
<td>Heavy bold borders</td>
</tr>
<tr>
<td><code>SingleDouble</code></td>
<td><pre>โโโ
โ โ
โโโ</pre></td>
<td>Single horizontal, double vertical</td>
</tr>
<tr>
<td><code>DoubleSingle</code></td>
<td><pre>โโโ
โ โ
โโโ</pre></td>
<td>Double horizontal, single vertical</td>
</tr>
<tr>
<td><code>Classic</code></td>
<td><pre>+--+
| |
+--+</pre></td>
<td>ASCII-compatible classic style</td>
</tr>
</table>
---
## ๐ Color Support
Boxen supports multiple color formats:
```rust
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
Boxen is highly optimized for speed and memory efficiency:
| 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 โก |
โ
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
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.
// Success messages
println!("{}",
simple_box("โ Build successful!")
);
// Error messages
println!("{}",
builder()
.border_color("red")
.render("โ Build failed")
.unwrap()
); |
// System status
println!("{}",
builder()
.title("System Status")
.border_color("green")
.render("All systems operational")
.unwrap()
); |
// User notifications
println!("{}",
builder()
.title("๐ Notification")
.padding(2)
.render("You have 3 new messages")
.unwrap()
); |
- ๐ API Documentation - Complete API reference
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_spinnerContributions are welcome! Here's how you can help:
- ๐ Report bugs - Open an issue with details
- ๐ก Suggest features - Share your ideas
- ๐ Improve docs - Help others learn
- ๐ง Submit PRs - Fix bugs or add features
Please read our Contributing Guide for details.
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.
- Inspired by the original boxen TypeScript library by Sindre Sorhus
- Built with โค๏ธ for the Rust community
- Thanks to all contributors
Made with ๐ฆ Rust โข Report Bug โข Request Feature