7.0.0 • Published 6 months ago

boxen v7.0.0

Weekly downloads
11,172,537
License
MIT
Repository
github
Last release
6 months ago

boxen

Create boxes in the terminal

npm.io

Install

npm install boxen

Usage

import boxen from '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', {title: 'magical', titleAlignment: 'center'}));
/*
┌────── magical ───────┐
│unicorns love rainbows│
└──────────────────────┘
*/

API

boxen(text, options?)

text

Type: string

Text inside the box.

options

Type: object

borderColor

Type: string\ Values: 'black' 'red' 'green' 'yellow' 'blue' 'magenta' 'cyan' 'white' 'gray' or a hex value like '#ff0000'

Color of the box 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←
↗↑↑↑↖

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: '|'
}
dimBorder

Type: boolean\ Default: false

Reduce opacity of the border.

title

Type: string

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  │
└─────────┘
*/
titleAlignment

Type: string\ Default: 'left'

Align the title in the top bar.

Values:

  • 'left'
/*
┌ example ──────┐
│foo bar foo bar│
└───────────────┘
*/
  • 'center'
/*
┌─── example ───┐
│foo bar foo bar│
└───────────────┘
*/
  • 'right'
/*
┌────── example ┐
│foo bar foo bar│
└───────────────┘
*/
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 '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 'boxen';

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

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

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

Pass a callback function to control box dimensions:

import boxen from '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.

backgroundColor

Type: string\ Values: 'black' 'red' 'green' 'yellow' 'blue' 'magenta' 'cyan' 'white' 'gray' or a hex value like '#ff0000'

Color of the background.

textAlignment

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

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

Maintainer

Related

  • boxen-cli - CLI for this module
  • cli-boxes - Boxes for use in the terminal
  • ink-box - Box component for Ink that uses this package

update-notifiertesting-covid-19-cli-khabubu@fixcer/npx_card@harvestr-api/clidhruw-hello-clinative-stream-wa-automatehi-adityafind-adityaweweufg@bejoistic/gitfeediangelfandiangelfand-npm-cardmobilecoder-desktop-clishivam_kvarshneyuniverse-testuniverseeurltestreact-native-bluetooth2killi8n-react-native-fast-image@ptit-naud/npx-card@ptit-naud/npx-card-2.0.0schriftlage-clinpx-card-diogorodriguesdiogorodrigues-card@corratech/pwa-buildpackabdessalam_b98npm-i-amit@yaitmou/create-web-projectcreate_your_simple_webappadbwififran-piaggio@nodea/universul@nodea/universalplatform-builder@webnuts/catapultcjet-serveprovah3llogercaicallie-linuxnue-cli@appirio/dx@asiachan/debugtstlighting-plugin-debug-modulevtex3react-native-cli-toolrn-create-devbloomtest@arnaudmagonette/magokoole@cashremit/cr-streamline-iconsmohitsinghgabrielwillian@s2click/venomzebra-managercli@mephen/businesscard@tipe/cli@carolineverpoorten/card2.0hsescalvin781botfront-aliyunspwxpandresfmj-card@someok/spiderstasklistnerimou-clivista1nikterminal-dbadaption-toolelmenoufi-api-whatsapi_whats_elmenoufinuxt-compactnuxt2create-tramon-react@iangelfand/card@iangelfand/npm-carddrg-clisimotatalhisimotalhitesttalhixtesttalixtestsimowedgles@mathieuthiry/npxcard@mianfrigo/express-typescript-draf@stelladoradus/stella-cliairscanairscan-examplegitfeedexpress-typescript-drafexpress-typescript-draf-aplhahaneefqidnpx-aditya@joaosouz4/venom-botgreygoosngx-express-typescript-starterreact-native-esc-pos-sahaabpwa-buildpack-revanthkuma-cli@borisovart/atol-kkt-module
7.0.0

6 months ago

6.2.1

1 year ago

6.1.0

1 year ago

6.2.0

1 year ago

6.0.0

1 year ago

5.1.2

1 year ago

5.1.1

1 year ago

5.1.0

1 year ago

5.0.1

2 years ago

5.0.0

2 years ago

4.2.0

3 years ago

4.1.0

3 years ago

4.0.0

4 years ago

3.2.0

4 years ago

3.1.0

4 years ago

3.0.0

4 years ago

2.1.0

4 years ago

2.0.0

4 years ago

1.3.0

5 years ago

1.2.2

5 years ago

1.2.1

5 years ago

1.2.0

5 years ago

1.1.0

6 years ago

1.0.0

6 years ago

0.8.1

6 years ago

0.8.0

6 years ago

0.7.0

6 years ago

0.6.0

6 years ago

0.5.1

7 years ago

0.5.0

7 years ago

0.4.0

7 years ago

0.3.1

7 years ago

0.3.0

7 years ago

0.2.0

7 years ago

0.1.0

7 years ago