@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.

Installation

npm install @davidwells/box-logger

Usage

Box

Create 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')

Box Options

OptionTypeDefaultDescription
contentstring | Section | function-Content (or function receiving { innerWidth })
titlestring | Section-Title section at top of box
fontStyle'normal' | 'bold''normal'Font style
textAlign'left' | 'center' | 'right''left'Text alignment
colorstring-Text color (chalk color or hex like '#ff0000')
backgroundColorstring-Background color (chalk color or hex)
paddingTopnumber0Newlines before content
paddingBottomnumber0Newlines after content
paddingLeftnumber2Spaces for left padding
paddingRightnumber2Spaces for right padding
borderColorstring-Border color (chalk color or hex)
borderStylestring'normal'Border style (see below)
borderTopbooleantrueShow top border
borderBottombooleantrueShow bottom border
borderLeftbooleantrueShow left border
borderRightbooleantrueShow right border
borderTextstring-Text embedded in top border
borderTextColorstring-Color for border text
borderTextAlign'left' | 'center' | 'right''left'Border text alignment
widthnumber | string-Fixed width
minWidthnumber | string-Minimum width ('100%' for full width)
maxWidthnumber | stringterminal widthMaximum width
marginTopnumber0Newlines before box
marginBottomnumber0Newlines after box
marginLeftnumber0Spaces before each line
wrapTextbooleantrueWrap text to fit inside box
typestring-Box type: 'success', 'error', 'warning', 'info'
iconstring-Custom icon
headerbooleanfalseHeader mode (no left border)
edgesobject-Custom border symbols

Border Styles

  • 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 all
  • filled - For use with backgroundColor

Section Object

Title 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

Stacked Boxes

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'
}))

Horizontal Boxes

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).

Line

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'
}))

Line Options

OptionTypeDefaultDescription
textstring-Text to display (use with textAlign)
leftstring-Left-aligned text
rightstring-Right-aligned text
centerstring-Center-aligned text
colorstring-Text color
backgroundColorstring-Background color for text
lineBackgroundColorstring-Background for entire line
fontStyle'normal' | 'bold''normal'Font style
borderColorstring-Line color
borderStylestring'normal'Line style
textAlign'left' | 'center' | 'right''center'Text alignment
paddingLeftnumber4Left padding
paddingRightnumber4Right padding
minWidthnumber | string-Minimum width
maxWidthnumber | stringterminal widthMaximum width
linesnumber-Generate multiple blank lines

Typed Variants

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')

Error Handling

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
}

Examples

Basic Box

┌─────────────┐
│  Hello World  │
└─────────────┘

Rounded Box with Title

╭──────────────────────╮
│  My Title            │
├──────────────────────┤
│  Content goes here   │
╰──────────────────────╯

Bold Box

┏━━━━━━━━━━━━━━━━━━━━━━┓
┃  Hello World         ┃
┗━━━━━━━━━━━━━━━━━━━━━━┛

Header (No Left Border)

──────────────────────────────┐
  Hello World                 │
──────────────────────────────┘

Line with Text

────────── Section Title ──────────

Line with Left and Right

──── Section ──────────── v1.2.3 ────

Utilities

terminalSize

Get the current terminal dimensions:

const { terminalSize } = require('@davidwells/box-logger')

const { columns, rows } = terminalSize()
console.log(`Terminal is ${columns}x${rows}`)

getInnerWidth

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 makeBox

License

MIT

Other rendering libs