BoxenUsage Guide
Usage Guide
Complete guide to all border styles, options, and features in @visulima/boxen.
Last updated:
Usage Guide
Complete guide to using @visulima/boxen for creating terminal boxes.
Border Styles
Built-in Styles
single (default):
import { boxen } from "@visulima/boxen";
console.log(boxen("single", { borderStyle: "single" }));Output:
┌──────┐
│single│
└──────┘double:
console.log(boxen("double", { borderStyle: "double" }));Output:
╔══════╗
║double║
╚══════╝round:
console.log(boxen("round", { borderStyle: "round" }));Output:
╭─────╮
│round│
╰─────╯bold:
console.log(boxen("bold", { borderStyle: "bold" }));Output:
┏━━━━┓
┃bold┃
┗━━━━┛singleDouble (single horizontal, double vertical):
console.log(boxen("singleDouble", { borderStyle: "singleDouble" }));Output:
╓────────────╖
║singleDouble║
╙────────────╜doubleSingle (double horizontal, single vertical):
console.log(boxen("doubleSingle", { borderStyle: "doubleSingle" }));Output:
╒════════════╕
│doubleSingle│
╘════════════╛classic:
console.log(boxen("classic", { borderStyle: "classic" }));Output:
+───────+
|classic|
+───────+arrow:
console.log(boxen("arrow", { borderStyle: "arrow" }));Output:
↘↓↓↓↓↓↙
→arrow←
↗↑↑↑↑↑↖Custom Border Characters
Define your own border style:
import { boxen } from "@visulima/boxen";
console.log(boxen("custom", {
borderStyle: {
topLeft: "╭",
topRight: "╮",
bottomLeft: "╰",
bottomRight: "╯",
top: "─",
bottom: "─",
left: "│",
right: "│",
},
}));Padding and Margins
Padding (Space Inside Box)
Uniform padding:
import { boxen } from "@visulima/boxen";
console.log(boxen("padded", { padding: 1 }));Output:
┌────────┐
│ │
│ padded │
│ │
└────────┘Individual sides:
console.log(boxen("custom padding", {
padding: {
top: 1,
right: 2,
bottom: 1,
left: 2,
},
}));Shorthand:
// Same as { top: 1, right: 2, bottom: 1, left: 2 }
boxen("text", { padding: [1, 2] });
// Same as { top: 1, right: 2, bottom: 3, left: 2 }
boxen("text", { padding: [1, 2, 3] });
// Same as { top: 1, right: 2, bottom: 3, left: 4 }
boxen("text", { padding: [1, 2, 3, 4] });Margins (Space Outside Box)
Uniform margin:
import { boxen } from "@visulima/boxen";
console.log(boxen("margin", { margin: 1 }));Output:
┌──────┐
│margin│
└──────┘Individual sides:
console.log(boxen("custom margin", {
margin: {
top: 1,
right: 2,
bottom: 1,
left: 2,
},
}));Text Alignment
Horizontal Alignment
Left aligned (default):
import { boxen } from "@visulima/boxen";
console.log(boxen("Left\nAligned\nText", {
textAlignment: "left",
padding: 1,
}));Center aligned:
console.log(boxen("Center\nAligned\nText", {
textAlignment: "center",
padding: 1,
}));Output:
┌─────────┐
│ │
│ Center │
│ Aligned │
│ Text │
│ │
└─────────┘Right aligned:
console.log(boxen("Right\nAligned\nText", {
textAlignment: "right",
padding: 1,
}));Output:
┌─────────┐
│ │
│ Right │
│ Aligned │
│ Text │
│ │
└─────────┘Headers and Footers
Header Text
Centered header:
import { boxen } from "@visulima/boxen";
console.log(boxen("Content goes here", {
headerText: "Title",
headerAlignment: "center",
}));Output:
┌───── Title ─────┐
│Content goes here│
└─────────────────┘Left aligned header:
console.log(boxen("Content", {
headerText: "Left",
headerAlignment: "left",
}));Output:
┌─ Left ──────┐
│Content │
└─────────────┘Right aligned header:
console.log(boxen("Content", {
headerText: "Right",
headerAlignment: "right",
}));Output:
┌───────── Right ─┐
│Content │
└─────────────────┘Footer Text
Centered footer:
console.log(boxen("Content", {
footerText: "Footer",
footerAlignment: "center",
}));Output:
┌───────────────┐
│Content │
└─── Footer ────┘Combined Headers and Footers
console.log(boxen("Main content here", {
headerText: "Header",
headerAlignment: "center",
footerText: "Footer",
footerAlignment: "center",
padding: 1,
}));Output:
┌──── Header ────┐
│ │
│ Main content │
│ here │
│ │
└──── Footer ────┘Border Coloring
Simple Color
import { boxen } from "@visulima/boxen";
import { green } from "@visulima/colorize";
console.log(boxen("Success!", {
borderColor: () => green("─"),
}));Position-Based Coloring
Color different parts of the border independently:
import { boxen } from "@visulima/boxen";
import { red, green, yellow, blue } from "@visulima/colorize";
console.log(boxen("Colorful!", {
borderColor: (border, position) => {
// Top border
if (["top", "topLeft", "topRight"].includes(position)) {
return red(border);
}
// Left border
if (position === "left") {
return yellow(border);
}
// Right border
if (position === "right") {
return green(border);
}
// Bottom border
if (["bottom", "bottomLeft", "bottomRight"].includes(position)) {
return blue(border);
}
return border;
},
}));Border Positions:
topLeft- Top left cornertop- Top horizontal linetopRight- Top right cornerleft- Left vertical lineright- Right vertical linebottomLeft- Bottom left cornerbottom- Bottom horizontal linebottomRight- Bottom right corner
Gradient Borders
import { boxen } from "@visulima/boxen";
import { gradient } from "@visulima/colorize/gradient";
const gradientFn = gradient("cyan", "pink");
console.log(boxen("Gradient borders!", {
borderColor: (border, position, length) => {
return gradientFn(border);
},
}));Width Control
Fixed Width
Set maximum box width:
import { boxen } from "@visulima/boxen";
console.log(boxen("This is a longer text that will wrap", {
width: 20,
}));Output:
┌──────────────────┐
│This is a longer │
│text that will │
│wrap │
└──────────────────┘Full Width
Use terminal width:
import { boxen } from "@visulima/boxen";
console.log(boxen("Full width box", {
width: "terminal",
textAlignment: "center",
}));Advanced Examples
Status Box with Icons
import { boxen } from "@visulima/boxen";
import { green, red, yellow } from "@visulima/colorize";
function statusBox(status: "success" | "error" | "warning", message: string) {
const configs = {
success: {
icon: "✓",
color: green,
border: "round",
},
error: {
icon: "✗",
color: red,
border: "double",
},
warning: {
icon: "⚠",
color: yellow,
border: "bold",
},
};
const config = configs[status];
return boxen(`${config.icon} ${message}`, {
padding: 1,
borderStyle: config.border as any,
borderColor: () => config.color("─"),
});
}
console.log(statusBox("success", "Build completed"));
console.log(statusBox("error", "Build failed"));
console.log(statusBox("warning", "Deprecated API"));Information Panel
import { boxen } from "@visulima/boxen";
import { gray, cyan } from "@visulima/colorize";
const info = [
`${gray("Name:")} ${cyan("MyApp")}`,
`${gray("Version:")} ${cyan("1.0.0")}`,
`${gray("Status:")} ${cyan("Running")}`,
`${gray("Port:")} ${cyan("3000")}`,
].join("\n");
console.log(boxen(info, {
padding: 1,
headerText: "Application Info",
headerAlignment: "center",
borderStyle: "double",
}));Multi-Section Box
import { boxen } from "@visulima/boxen";
import { bold, dim } from "@visulima/colorize";
const sections = [
bold("Section 1"),
"Content for section 1",
"",
bold("Section 2"),
"Content for section 2",
"",
dim("Note: This is a multi-section box"),
].join("\n");
console.log(boxen(sections, {
padding: 1,
headerText: "Documentation",
footerText: "Press Enter to continue",
footerAlignment: "center",
}));