boxen

  • Version 8.0.1
  • Published
  • 23.7 kB
  • 8 dependencies
  • MIT license

Install

npm i boxen
yarn add boxen
pnpm add boxen

Overview

Create boxes in the terminal

Index

Functions

function boxen

boxen: (text: string, options?: Options) => string;
  • Creates a box in the terminal.

    Parameter text

    The text inside the box.

    Returns

    The box.

    Example 1

    import boxen from 'boxen';
    console.log(boxen('unicorn', {padding: 1}));
    // ┌─────────────┐
    // │ │
    // │ unicorn │
    // │ │
    // └─────────────┘
    console.log(boxen('unicorn', {padding: 1, margin: 1, borderStyle: 'double'}));
    //
    // ╔═════════════╗
    // ║ ║
    // ║ unicorn ║
    // ║ ║
    // ╚═════════════╝
    //

Type Aliases

type Boxes

type Boxes = {
readonly none: BoxStyle;
} & CLIBoxes;
  • All box styles.

type CustomBorderStyle

type CustomBorderStyle = {
/**
@deprecated Use `top` and `bottom` instead.
*/
horizontal?: string;
/**
@deprecated Use `left` and `right` instead.
*/
vertical?: string;
} & BoxStyle;
  • Characters used for custom border.

    Example 1

    // attttb
    // l r
    // dbbbbc
    const border: CustomBorderStyle = {
    topLeft: 'a',
    topRight: 'b',
    bottomRight: 'c',
    bottomLeft: 'd',
    left: 'l',
    right: 'r',
    top: 't',
    bottom: 'b',
    };

type Options

type Options = {
/**
Color of the box border.
*/
readonly borderColor?: LiteralUnion<
| 'black'
| 'red'
| 'green'
| 'yellow'
| 'blue'
| 'magenta'
| 'cyan'
| 'white'
| 'gray'
| 'grey'
| 'blackBright'
| 'redBright'
| 'greenBright'
| 'yellowBright'
| 'blueBright'
| 'magentaBright'
| 'cyanBright'
| 'whiteBright',
string
>;
/**
Style of the box border.
@default 'single'
*/
readonly borderStyle?: keyof Boxes | CustomBorderStyle;
/**
Reduce opacity of the border.
@default false
*/
readonly dimBorder?: boolean;
/**
Space between the text and box border.
@default 0
*/
readonly padding?: number | Spacing;
/**
Space around the box.
@default 0
*/
readonly margin?: number | Spacing;
/**
Float the box on the available terminal screen space.
@default 'left'
*/
readonly float?: 'left' | 'right' | 'center';
/**
Color of the background.
*/
readonly backgroundColor?: LiteralUnion<
| 'black'
| 'red'
| 'green'
| 'yellow'
| 'blue'
| 'magenta'
| 'cyan'
| 'white'
| 'blackBright'
| 'redBright'
| 'greenBright'
| 'yellowBright'
| 'blueBright'
| 'magentaBright'
| 'cyanBright'
| 'whiteBright',
string
>;
/**
Align the text in the box based on the widest line.
@default 'left'
@deprecated Use `textAlignment` instead.
*/
readonly align?: 'left' | 'right' | 'center';
/**
Align the text in the box based on the widest line.
@default 'left'
*/
readonly textAlignment?: 'left' | 'right' | 'center';
/**
Display a title at the top of the box.
If needed, the box will horizontally expand to fit the title.
@example
```
console.log(boxen('foo bar', {title: 'example'}));
// ┌ example ┐
// │foo bar │
// └─────────┘
```
*/
readonly title?: string;
/**
Align the title in the top bar.
@default 'left'
@example
```
console.log(boxen('foo bar foo bar', {title: 'example', titleAlignment: 'center'}));
// ┌─── example ───┐
// │foo bar foo bar│
// └───────────────┘
console.log(boxen('foo bar foo bar', {title: 'example', titleAlignment: 'right'}));
// ┌────── example ┐
// │foo bar foo bar│
// └───────────────┘
```
*/
readonly titleAlignment?: 'left' | 'right' | 'center';
/**
Set a fixed width for the box.
__Note__: This disables terminal overflow handling and may cause the box to look broken if the user's terminal is not wide enough.
@example
```
import boxen from 'boxen';
console.log(boxen('foo bar', {width: 15}));
// ┌─────────────┐
// │foo bar │
// └─────────────┘
```
*/
readonly width?: number;
/**
Set a fixed height for the box.
__Note__: This option will crop overflowing content.
@example
```
import boxen from 'boxen';
console.log(boxen('foo bar', {height: 5}));
// ┌───────┐
// │foo bar│
// │ │
// │ │
// └───────┘
```
*/
readonly height?: number;
/**
__boolean__: Whether or not to fit all available space within the terminal.
__function__: Pass a callback function to control box dimensions.
@example
```
import boxen from 'boxen';
console.log(boxen('foo bar', {
fullscreen: (width, height) => [width, height - 1],
}));
```
*/
readonly fullscreen?:
| boolean
| ((width: number, height: number) => [width: number, height: number]);
};

    type Spacing

    type Spacing = {
    readonly top?: number;
    readonly right?: number;
    readonly bottom?: number;
    readonly left?: number;
    };
    • Spacing used for padding and margin.

    Package Files (1)

    Dependencies (8)

    Dev Dependencies (4)

    Peer Dependencies (0)

    No peer dependencies.

    Badge

    To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

    You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/boxen.

    • Markdown
      [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/boxen)
    • HTML
      <a href="https://www.jsdocs.io/package/boxen"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>