@selfteachme/boxerjs

A beautiful and flexible utility for drawing boxes around terminal content. Perfect for CLI applications using yargs and chalk.

Features

• Draw boxes around any text content
• Flexible width options: content-based, fixed, or terminal width
• Text alignment options: left, center, or right
• Customizable padding and margins
• Custom border styles and colors using chalk
• Full TypeScript support
• Compatible with yargs and chalk

Installation

npm install @selfteachme/boxerjs chalk
# If you're using yargs
npm install yargs

Usage

Basic Example

import { Box } from '@selfteachme/boxerjs';
import chalk from 'chalk';

const box = new Box({
  content: 'Hello, World!',
  color: chalk.green,
  borderColor: chalk.blue
});

console.log(box.toString());

Output:

╭───────────────╮
│ Hello, World! │
╰───────────────╯

Terminal-width Box with Alignment

const box = new Box({
  content: 'Centered text in a terminal-width box',
  width: 'terminal',
  align: 'center',  // 'left', 'center', or 'right'
  padding: [1, 2],
  color: chalk.yellow
});

console.log(box.toString());

Output:

╭──────────────────────────────────────────────────────────────╮
│                                                              │
│            Centered text in a terminal-width box             │
│                                                              │
╰──────────────────────────────────────────────────────────────╯

With Yargs

import yargs from 'yargs';
import { Box } from '@selfteachme/boxerjs';
import chalk from 'chalk';

yargs
  .command({
    command: 'greet <name>',
    describe: 'Greet someone with a fancy box',
    builder: {
      color: {
        describe: 'Text color',
        type: 'string',
        default: 'green'
      },
      align: {
        describe: 'Text alignment',
        choices: ['left', 'center', 'right'],
        default: 'left'
      }
    },
    handler: (argv) => {
      const box = new Box({
        content: `Hello, ${argv.name}!`,
        width: 'terminal',
        align: argv.align,
        color: chalk[argv.color],
        padding: [1, 2],
        margin: [1, 0]
      });
      
      console.log(box.toString());
    }
  })
  .argv;

Advanced Options

const box = new Box({
  content: 'Multi-line\ncontent example',
  width: 'terminal',     // or 'content' or fixed number
  align: 'center',       // or 'left' or 'right'
  padding: [1, 2],       // [vertical, horizontal] or single number
  margin: [1, 2],        // [vertical, horizontal] or single number
  color: chalk.green,
  borderColor: chalk.blue,
  style: {
    topLeft: '╔',
    topRight: '╗',
    bottomLeft: '╚',
    bottomRight: '╝',
    horizontal: '═',
    vertical: '║'
  }
});

API Reference

BoxOptions

| Option | Type | Description | |--------|------|-------------| | content | string | The text content to wrap in a box | | width | 'content' | 'terminal' | number | Box width strategy (default: 'content') | | align | 'left' | 'center' | 'right' | Text alignment within the box (default: 'left') | | padding | number | [number, number] | Inner padding [vertical, horizontal] (default: 0) | | margin | number | [number, number] | Outer margin [vertical, horizontal] (default: 0) | | style | BoxStyle | Custom border characters | | color | chalk.Chalk | Text color using chalk | | borderColor | chalk.Chalk | Border color using chalk |

BoxStyle

| Property | Default | Description | |----------|---------|-------------| | topLeft | '╭' | Top-left corner character | | topRight | '╮' | Top-right corner character | | bottomLeft | '╰' | Bottom-left corner character | | bottomRight | '╯' | Bottom-right corner character | | horizontal | '─' | Horizontal border character | | vertical | '│' | Vertical border character |

License

MIT