# Boxen
[](https://crates.io/crates/boxen)
[](https://docs.rs/boxen)
[](https://github.com/sabry-awad97/boxen/actions)
[](https://github.com/sabry-awad97/boxen#license)
A Rust implementation of the popular [boxen](https://github.com/sindresorhus/boxen) library for creating styled terminal boxes around text.
## Features
- ๐จ **Multiple border styles** - Single, double, round, bold, and custom borders
- ๐ **Flexible alignment** - Left, center, and right text alignment
- ๐ฏ **Precise spacing** - Fine-grained control over padding and margins
- ๐ **Rich colors** - Support for named colors, hex codes, and RGB values
- ๐ **Title support** - Add titles with customizable positioning
- ๐ค **Unicode aware** - Proper handling of Unicode characters and ANSI escape sequences
- ๐ฑ **Responsive** - Fullscreen mode and terminal-aware layouts
- โก **Performance optimized** - Minimal allocations and efficient text processing
- ๐ก๏ธ **Type safe** - Comprehensive error handling with descriptive messages
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
boxen = "0.1.2"
```
## Quick Start
```rust
use ::boxen::{boxen, builder, BorderStyle, TextAlignment};
fn main() {
// Simple box with default settings
let simple = boxen("Hello, World!", None).unwrap();
println!("{}", simple);
// Using the builder pattern for more control
let fancy = builder()
.border_style(BorderStyle::Double)
.padding(2)
.margin(1)
.text_alignment(TextAlignment::Center)
.title("Greeting")
.border_color("blue")
.render("Hello, World!")
.unwrap();
println!("{}", fancy);
}
```
## Examples
### Basic Usage
```rust
use ::boxen::boxen;
let result = boxen("Simple box", None).unwrap();
println!("{}", result);
```
Output:
```
โโโโโโโโโโโโ
โSimple boxโ
โโโโโโโโโโโโ
```
### Builder Pattern
```rust
use ::boxen::{builder, BorderStyle, TextAlignment};
let result = builder()
.border_style(BorderStyle::Round)
.padding(1)
.text_alignment(TextAlignment::Center)
.width(20)
.title("Status")
.border_color("green")
.render("All systems operational")
.unwrap();
println!("{}", result);
```
Output:
```
โญโโโ Status โโโโโฎ
โ โ
โ All systems โ
โ operational โ
โ โ
โฐโโโโโโโโโโโโโโโโฏ
```
### Convenience Functions
```rust
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
```rust
use ::boxen::{builder, BorderStyle, TextAlignment, 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)
.height(8)
.title("๐ Celebration")
.border_color("#ff6b6b")
.background_color("#ffe66d")
.render("Congratulations!\nYou've mastered boxen!")
.unwrap();
println!("{}", result);
```
### Error Handling
```rust
use ::boxen::{builder, BoxenError};
match builder()
.width(5) // Too narrow
.padding(10) // Too much padding
.render("This won't fit") {
Ok(result) => println!("{}", result),
Err(BoxenError::ConfigurationError(msg)) => {
eprintln!("Configuration error: {}", msg);
}
Err(e) => eprintln!("Error: {}", e),
}
```
## Border Styles
Boxen supports various border styles:
| `Single` | `โโโโ โโโโ` |
| `Double` | `โโโโ โโโโ` |
| `Round` | `โญโโฎโ โโฐโโฏ` |
| `Bold` | `โโโโ โโโโ` |
| `SingleDouble` | `โโโโ โโโโ` |
| `DoubleSingle` | `โโโโ โโโโ` |
| `Classic` | `+--+ | | | | +--+` |
## Color Support
Boxen supports multiple color formats:
```rust
use ::boxen::builder;
// Named colors
builder().border_color("red");
builder().background_color("blue");
// Hex colors
builder().border_color("#ff0000");
builder().background_color("#0000ff");
// RGB colors
builder().border_color((255, 0, 0));
builder().background_color((0, 0, 255));
```
## Performance
Boxen is optimized for performance:
- **Minimal allocations**: Smart string buffer management
- **Unicode aware**: Efficient width calculation for international text
- **ANSI handling**: Proper escape sequence processing
- **Caching**: Terminal dimensions and expensive calculations are cached
Benchmark results on a modern machine:
- Simple box: ~10ฮผs
- Complex styled box: ~50ฮผs
- Large text (1000 lines): ~2ms
## Examples
Run the included examples to see boxen in action:
```bash
# 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
# 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
```
## Documentation
- [API Documentation](https://docs.rs/boxen) - Complete API reference
- [Usage Guide](docs/usage.md) - Detailed usage examples
- [Customization Guide](docs/customization.md) - Advanced styling techniques
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## License
This project is licensed under either of
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
## Acknowledgments
- Inspired by the original [boxen](https://github.com/sindresorhus/boxen) TypeScript library by Sindre Sorhus
- Built with โค๏ธ for the Rust community
---
<div align="center">
<sub>Built with ๐ฆ Rust</sub>
</div>