@davidwells/box-logger creates formatted terminal boxes, headers, horizontal lines, and multi-column layouts for CLI output.
It is small UI infrastructure for command-line tools: make important output easier to scan without forcing every script to rebuild terminal formatting from scratch.
Full documentation, synced from the package README:
A simple utility for creating formatted text boxes, headers, and lines in the terminal.
npm install @davidwells/box-loggerCreate a box around text with customizable borders, padding, and styling.
const { makeBox, logBox } = require('@davidwells/box-logger')
// Simple usage with a string
console.log(makeBox('Hello World'))
// With options
console.log(makeBox({
content: 'Hello World',
textAlign: 'center',
paddingLeft: 4,
paddingRight: 4,
borderColor: 'green',
borderStyle: 'bold'
}))
// With title and content
console.log(makeBox({
title: 'My Title',
content: 'Box content here',
borderStyle: 'rounded'
}))
// Hex colors are supported
console.log(makeBox({
content: 'Custom colors',
borderColor: '#4287f5',
backgroundColor: '#1a1a2e'
}))
// Dynamic content - function receives { innerWidth } for sizing
console.log(makeBox({
title: 'Dynamic Width',
content: ({ innerWidth }) => generateContent({ width: innerWidth }),
paddingLeft: 1,
paddingRight: 0
}))
// Async content - use makeBoxAsync for async functions
const box = await makeBoxAsync({
title: 'Async Content',
content: async ({ innerWidth }) => await fetchData({ width: innerWidth })
})
console.log(box)
// Call logger directly
logBox('Log the box directly')| Option | Type | Default | Description |
|---|---|---|---|
content | string | Section | function | - | Content (or function receiving { innerWidth }) |
title | string | Section | - | Title section at top of box |
fontStyle | 'normal' | 'bold' | 'normal' | Font style |
textAlign | 'left' | 'center' | 'right' | 'left' | Text alignment |
color | string | - | Text color (chalk color or hex like '#ff0000') |
backgroundColor | string | - | Background color (chalk color or hex) |
paddingTop | number | 0 | Newlines before content |
paddingBottom | number | 0 | Newlines after content |
paddingLeft | number | 2 | Spaces for left padding |
paddingRight | number | 2 | Spaces for right padding |
borderColor | string | - | Border color (chalk color or hex) |
borderStyle | string | 'normal' | Border style (see below) |
borderTop | boolean | true | Show top border |
borderBottom | boolean | true | Show bottom border |
borderLeft | boolean | true | Show left border |
borderRight | boolean | true | Show right border |
borderText | string | - | Text embedded in top border |
borderTextColor | string | - | Color for border text |
borderTextAlign | 'left' | 'center' | 'right' | 'left' | Border text alignment |
width | number | string | - | Fixed width |
minWidth | number | string | - | Minimum width ('100%' for full width) |
maxWidth | number | string | terminal width | Maximum width |
marginTop | number | 0 | Newlines before box |
marginBottom | number | 0 | Newlines after box |
marginLeft | number | 0 | Spaces before each line |
wrapText | boolean | true | Wrap text to fit inside box |
type | string | - | Box type: 'success', 'error', 'warning', 'info' |
icon | string | - | Custom icon |
header | boolean | false | Header mode (no left border) |
edges | object | - | Custom border symbols |
normal - Standard box drawing characters (─│┌┐└┘)rounded - Rounded corners (╭╮╰╯)bold - Heavy weight borders (━┃┏┓┗┛)double - Double line borders (═║╔╗╚╝)dashed - Dashed horizontal lines (╌)dotted - Dotted horizontal lines (┈)thick - Block characters (█▀▄)half-thick - Half block borders (▐▌▔▂)ultra-thick - Full block borders (█)ascii - ASCII fallback (-|+)dots - Bullet dots (•)circles - Hollow circles (○)stars - Sparkle stars (✨)triple - Triple lines (≡)transparent - Invisible borders (spaces)none - No borders at allfilled - For use with backgroundColorTitle and content can be strings or Section objects for more control:
makeBox({
title: {
left: 'Title',
right: 'v1.0.0',
fontStyle: 'bold',
color: 'cyan'
},
content: {
left: 'Description',
right: 'Status: OK',
color: 'green'
}
})Section properties: left, right, center, color, fontStyle, paddingLeft, paddingRight, paddingTop, paddingBottom, truncate
Stack multiple boxes vertically with shared borders:
const { makeStackedBoxes } = require('@davidwells/box-logger')
console.log(makeStackedBoxes([
{ title: 'Box 1', content: 'First box content' },
{ title: 'Box 2', content: 'Second box content' },
{ title: 'Box 3', content: 'Third box content' }
], {
borderStyle: 'rounded',
borderColor: 'cyan'
}))Render boxes side by side:
const { makeHorizontalBoxes } = require('@davidwells/box-logger')
console.log(makeHorizontalBoxes([
{ content: 'Left box' },
{ content: 'Middle box' },
{ content: 'Right box' }
], {
gap: 2,
mergeBoxes: true // Merge adjacent borders
}))Options: gap, marginLeft, connectRows, justifyContent ('flex-start', 'flex-end', 'space-between'), wrap, mergeBoxes
Create a header (box with no left border):
const { makeHeader, logHeader } = require('@davidwells/box-logger')
// Simple usage
console.log(makeHeader('Hello World'))
// With options
console.log(makeHeader({
content: 'Hello World',
borderColor: 'blue'
}))
// Typed variants
logHeader.success('Operation completed')
logHeader.error('An error occurred')
logHeader.warning('Please be careful')
logHeader.info('Information')Header uses the same options as Box (it's just header: true under the hood).
Create horizontal lines with optional text:
const { makeLine, logLine } = require('@davidwells/box-logger')
// Simple line
console.log(makeLine())
// Line with centered text
console.log(makeLine('Section Title'))
// Line with options
console.log(makeLine({
text: 'Styled text',
fontStyle: 'bold',
borderColor: 'green'
}))
// Left and right text
console.log(makeLine({
left: 'Section',
right: 'v1.2.3',
borderColor: 'cyan'
}))
// All three positions
console.log(makeLine({
left: 'Left',
center: 'Center',
right: 'Right'
}))| Option | Type | Default | Description |
|---|---|---|---|
text | string | - | Text to display (use with textAlign) |
left | string | - | Left-aligned text |
right | string | - | Right-aligned text |
center | string | - | Center-aligned text |
color | string | - | Text color |
backgroundColor | string | - | Background color for text |
lineBackgroundColor | string | - | Background for entire line |
fontStyle | 'normal' | 'bold' | 'normal' | Font style |
borderColor | string | - | Line color |
borderStyle | string | 'normal' | Line style |
textAlign | 'left' | 'center' | 'right' | 'center' | Text alignment |
paddingLeft | number | 4 | Left padding |
paddingRight | number | 4 | Right padding |
minWidth | number | string | - | Minimum width |
maxWidth | number | string | terminal width | Maximum width |
lines | number | - | Generate multiple blank lines |
All log functions have typed variants with automatic icons and colors:
const { logBox, logHeader, logLine } = require('@davidwells/box-logger')
// Box variants
logBox.success('Operation completed successfully')
logBox.error('An error occurred')
logBox.warning('Please be careful')
logBox.info('Here is some information')
// Header variants
logHeader.success('Success!')
logHeader.error('Error!')
// Line variants
logLine.success('Success line')
logLine.error('Error line')Pass an Error object to logBox for formatted error display:
try {
throw new Error('Something went wrong')
} catch (err) {
logBox.error(err) // Shows error name, message, and cleaned stack trace
}┌─────────────┐
│ Hello World │
└─────────────┘╭──────────────────────╮
│ My Title │
├──────────────────────┤
│ Content goes here │
╰──────────────────────╯┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ Hello World ┃
┗━━━━━━━━━━━━━━━━━━━━━━┛──────────────────────────────┐
Hello World │
──────────────────────────────┘────────── Section Title ────────────── Section ──────────── v1.2.3 ────Get the current terminal dimensions:
const { terminalSize } = require('@davidwells/box-logger')
const { columns, rows } = terminalSize()
console.log(`Terminal is ${columns}x${rows}`)Calculate the inner content width for a box configuration:
const { getInnerWidth } = require('@davidwells/box-logger')
const innerWidth = getInnerWidth({
paddingLeft: 1,
paddingRight: 0,
marginLeft: 5
})
// Use innerWidth to pre-size content before calling makeBoxMIT