1.0.30 • Published 4 months ago

@visulima/boxen v1.0.30

Weekly downloads
-
License
MIT
Repository
github
Last release
4 months ago

cli-boxes, string-width, terminal-size and wrap-ansi

typescript-image npm-image license-image



Install

npm install @visulima/boxen
yarn add @visulima/boxen
pnpm add @visulima/boxen

Usage

import { boxen } from "@visulima/boxen";

console.log(boxen("unicorn", { padding: 1 }));
/*
┌─────────────┐
│             │
│   unicorn   │
│             │
└─────────────┘
*/

console.log(boxen("unicorn", { padding: 1, margin: 1, borderStyle: "double" }));
/*
   ╔═════════════╗
   ║             ║
   ║   unicorn   ║
   ║             ║
   ╚═════════════╝

*/

console.log(
    boxen("unicorns love rainbows", {
        headerText: "magical",
        headerAlignment: "center",
    }),
);
/*
┌────── magical ───────┐
│unicorns love rainbows│
└──────────────────────┘
*/

console.log(
    boxen("unicorns love rainbows", {
        headerText: "magical",
        headerAlignment: "center",
        footerText: "magical",
        footerAlignment: "center",
    }),
);
/*
┌────── magical ───────┐
│unicorns love rainbows│
└────── magical ───────┘
*/

Check more examples in the examples/boxen folder.

API

boxen(text, options?)

text

Type: string

Text inside the box.

options

Type: object

borderColor

Type: (border: string, position: BorderPosition, length: number) => string\

Color of the box border.

import { boxen } from "@visulima/boxen";
import { red, green, yellow, blue } from "@visulima/colorize";

console.log(
    boxen("Hello, world!", {
        borderColor: (border, position) => {
            if (["top", "topLeft", "topRight"].includes(position)) {
                return red(border);
            }

            if (position === "left") {
                return yellow(border);
            }

            if (position === "right") {
                return green(border);
            }

            if (["bottom", "bottomLeft", "bottomRight"].includes(position)) {
                return blue(border);
            }
        },
    }),
);
borderStyle

Type: string | object\ Default: 'single'\ Values:

  • 'single'
┌───┐
│foo│
└───┘
  • 'double'
╔═══╗
║foo║
╚═══╝
  • 'round' ('single' sides with round corners)
╭───╮
│foo│
╰───╯
  • 'bold'
┏━━━┓
┃foo┃
┗━━━┛
  • 'singleDouble' ('single' on top and bottom, 'double' on right and left)
╓───╖
║foo║
╙───╜
  • 'doubleSingle' ('double' on top and bottom, 'single' on right and left)
╒═══╕
│foo│
╘═══╛
  • 'classic'
+---+
|foo|
+---+
  • 'arrow'
↘↓↓↓↙
→foo←
↗↑↑↑↖
  • 'none'
foo

Style of the box border.

Can be any of the above predefined styles or an object with the following keys:

{
    topLeft: '+',
    topRight: '+',
    bottomLeft: '+',
    bottomRight: '+',
    top: '-',
    bottom: '-',
    left: '|',
    right: '|'
}
headerText

Type: string

Display a title at the top of the box. If needed, the box will horizontally expand to fit the text.

Example:

import { boxen } from "@visulima/boxen";

console.log(boxen("foo bar", { headerText: "example" }));

/*
┌ example ┐
│foo bar  │
└─────────┘
*/
headerColor

Type: (text: string) => string

import { red } from "@visulima/colorize";
import { boxen } from "@visulima/boxen";

console.log(
    boxen("foo bar", {
        headerText: "example",
        headerColor: (text) => red(text),
    }),
);
headerAlignment

Type: string\ Default: 'left'

Align the text in the top bar.

Values:

  • 'left'
┌ example ──────┐
│foo bar foo bar│
└───────────────┘
  • 'center'
┌─── example ───┐
│foo bar foo bar│
└───────────────┘
  • 'right'
┌────── example ┐
│foo bar foo bar│
└───────────────┘
footerText

Type: string

Display a text at the bottom of the box. If needed, the box will horizontally expand to fit the text.

Example:

import { boxen } from "@visulima/boxen";

console.log(boxen("foo bar", { footerText: "example" }));

/*
┌─────────┐
│foo bar  │
└ example ┘
*/
footerColor

Type: (text: string) => string

import { red } from "@visulima/colorize";
import { boxen } from "@visulima/boxen";

console.log(
    boxen("foo bar", {
        footerText: "example",
        footerColor: (text) => red(text),
    }),
);
footerAlignment

Type: string\ Default: 'left'

Align the footer text.

Values:

  • 'left'
┌───────────────┐
│foo bar foo bar│
└ Footer Text ──┘
  • 'center'
┌───────────────┐
│foo bar foo bar│
└─── example ───┘
  • 'right'
┌───────────────┐
│foo bar foo bar│
└────── example ┘
width

Type: number

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.

import { boxen } from "@visulima/boxen";

console.log(boxen("foo bar", { width: 15 }));
// ┌─────────────┐
// │foo bar      │
// └─────────────┘
height

Type: number

Set a fixed height for the box.

Note: This option will crop overflowing content.

import { boxen } from "@visulima/boxen";

console.log(boxen("foo bar", { height: 5 }));
// ┌───────┐
// │foo bar│
// │       │
// │       │
// └───────┘
fullscreen

Type: boolean | (width: number, height: number) => [width: number, height: number]

Whether or not to fit all available space within the terminal.

Pass a callback function to control box dimensions:

import { boxen } from "@visulima/boxen";

console.log(
    boxen("foo bar", {
        fullscreen: (width, height) => [width, height - 1],
    }),
);
padding

Type: number | object\ Default: 0

Space between the text and box border.

Accepts a number or an object with any of the top, right, bottom, left properties. When a number is specified, the left/right padding is 3 times the top/bottom to make it look nice.

margin

Type: number | object\ Default: 0

Space around the box.

Accepts a number or an object with any of the top, right, bottom, left properties. When a number is specified, the left/right margin is 3 times the top/bottom to make it look nice.

float

Type: string\ Default: 'left'\ Values: 'right' 'center' 'left'

Float the box on the available terminal screen space.

textColor

Type: (text: string) => string\

import { bgRed } from "@visulima/colorize";
import { boxen } from "@visulima/boxen";

console.log(
    boxen("foo bar", {
        textColor: (text) => bgRed(text),
    }),
);
textAlignment

Type: string\ Default: 'left'\ Values: 'left' 'center' 'right'

Align the text in the box based on the widest line.

transformTabToSpace

Type: false | number\ Default: '4'

Transform tab characters to spaces. Set to false to disable.

Supported Node.js Versions

26.3 15:00 Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guidelines.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

License

The visulima boxen is open-sourced software licensed under the MIT

typescript-url: https://www.typescriptlang.org/ "TypeScript" "typescript"

1.0.29

6 months ago

1.0.28

6 months ago

1.0.30

4 months ago

1.0.26

6 months ago

1.0.27

6 months ago

1.0.25

6 months ago

1.0.24

6 months ago

1.0.23

7 months ago

1.0.22

7 months ago

1.0.21

9 months ago

1.0.20

9 months ago

1.0.19

10 months ago

1.0.18

10 months ago

1.0.17

10 months ago

1.0.16

10 months ago

1.0.15

10 months ago

1.0.14

11 months ago

1.0.13

12 months ago

1.0.12

12 months ago

1.0.11

1 year ago

1.0.10

1 year ago

1.0.9

1 year ago

1.0.8

1 year ago

1.0.7

1 year ago

1.0.6

1 year ago

1.0.5

1 year ago

1.0.4

1 year ago

1.0.3

1 year ago

1.0.2

1 year ago

1.0.1

1 year ago

1.0.0

1 year ago