box-logger

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({
  text: 'Hello World',
  textAlign: 'center',
  paddingLeft: 4,
  paddingRight: 4,
  borderColor: 'green',
  borderStyle: 'bold'
}))

// Call logger directly
logBox('Log the box directly')

Box Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | text | string | - | The text message to display in the box | | textStyle | 'normal' | 'bold' | 'normal' | Text style | | textAlign | 'left' | 'center' | 'right' | 'left' | Text alignment within the box | | textColor | string | - | Text color (any chalk color) | | title | string | - | The title to display at the top of the box | | titleStyle | 'normal' | 'bold' | 'normal' | Title style | | titleAlign | 'left' | 'center' | 'right' | 'left' | Title alignment within the box | | titleColor | string | - | Title color (any chalk color) | | paddingLeft | number | 2 | Number of spaces for left padding | | paddingRight | number | 2 | Number of spaces for right padding | | borderColor | string | - | Border color (any chalk color) | | borderStyle | 'normal' | 'bold' | 'dashed' | 'transparent' | 'normal' | Border style | | minWidth | number | string | - | Minimum width of the box. Set '100%' for full width | | maxWidth | number | terminal width | Maximum width of the box | | edges | BoxEdges | - | Custom border symbols | | adjustContentWidth | number | 0 | Additional padding for content | | wrapText | boolean | false | If true, wrap text to fit inside the box |

Header

Create a rectangular header with a line above and below the text.

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

// Simple usage with a string
console.log(makeHeader('Hello World'));

// With options
console.log(makeHeader({
  text: 'Hello World',
  borderColor: 'blue',
  paddingLeft: 4,
  paddingRight: 4,
  rightBorder: true
}));

Header Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | text | string | - | The text message to display in the header | | textStyle | 'normal' | 'bold' | 'normal' | Text style | | textAlign | 'left' | 'center' | 'right' | 'left' | Text alignment within the header | | textColor | string | - | Text color (any chalk color) | | title | string | - | The title to display at the top of the header | | titleStyle | 'normal' | 'bold' | 'normal' | Title style | | titleAlign | 'left' | 'center' | 'right' | 'left' | Title alignment within the header | | titleColor | string | - | Title color (any chalk color) | | borderColor | string | - | Border color (any chalk color) | | borderStyle | 'normal' | 'bold' | 'normal' | Border style | | paddingLeft | number | 2 | Number of spaces for left padding | | paddingRight | number | 2 | Number of spaces for right padding | | rightBorder | boolean | false | If true, adds a right border with corners like in box | | minWidth | number | string | - | Minimum width of the header | | maxWidth | number | terminal width | Maximum width of the header |

LogBox and LogHeader

Create pre-styled boxes and headers with success, error, warning, and info variants.

const { logBox, logHeader } = 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('Operation completed successfully')
logHeader.error('An error occurred')
logHeader.warning('Please be careful')
logHeader.info('Here is some information')

Examples

Basic Box

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

Centered Box with Green Border

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

Bold Box with Custom Padding

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

Box with Title

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃  Title is here                             ┃
┃━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┃
┃  This is a very long message that          ┃
┃  would normally create a wide box,         ┃
┃  but we are limiting its width to 30       ┃
┃  characters.                               ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Header Examples

──────────────────────────────
  Hello World
──────────────────────────────

Header with Right Border

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

Header with Title and Right Border

──────────────────────────────┐
  Centered Bold Title         │
  This header has a centered  │
  and bold title.             │
──────────────────────────────┘

Line Examples

──────────────────────────────

Line with Text

────────── Text in the middle ──────────

Line with Styled Text

────────── Styled text ──────────

Line with Colored Text

────────── Colored text ──────────

Line with Text Alignment

Left aligned text ──────────────────────
────────── Center aligned text ──────────
───────────────────── Right aligned text

Pre-styled Variants

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('Operation completed successfully')
logHeader.error('An error occurred')
logHeader.warning('Please be careful')
logHeader.info('Here is some information')

Line Variants

logLine.success('Success line with text')
logLine.error('Error line with text')
logLine.warning('Warning line with text')
logLine.info('Info line with text')

Advanced Examples

Box with Full Width

makeBox({
  text: 'This box will use the full terminal width',
  minWidth: '100%',
  borderColor: 'cyan',
  borderStyle: 'bold'
})

Header with Min and Max Width

makeHeader({
  text: 'This header has both min and max width constraints',
  minWidth: 40,
  maxWidth: 60,
  borderColor: 'magenta',
  borderStyle: 'bold'
})

Line with Custom Padding

makeLine({
  text: 'Left aligned with padding',
  textAlign: 'left',
  paddingLeft: 10,
  borderStyle: 'bold'
})

License

MIT

Other rendering libs

• https://github.com/tecfu/tty-table
• https://www.npmjs.com/package/boxen