gradient-boxen

A combo of gradient-string + boxen

gradient-boxen is a library that allows you to create fully customizable gradient boxes in the terminal. Because what's better than a gradient-y string and a cool terminal box? A gradient box!

It effectively combines the popular NPM packages boxen and gradient-string into one unified package.

🛠️ Install

Using npm

npm i gradient-boxen

Note This package is ESM only. Please check out this guide on how to convert your project to ESM

🔗 Usage

Note This package will properly display gradient boxes only in terminals with TrueColor support, ie, 16 million colors, in order to properly display the gradients. This should work alright in most terminal and shells

• Using an array of gradient colors

import gradientBox from 'gradient-boxen';

console.log(
  gradientBox(
    'I love gradients!',
    {
      borderStyle: 'round',
      padding: 1,
      margin: 1,
    },
    ['#11998e', '#38ef7d']
  )
);

Output:

• Using a predefined preset

import gradientBox from 'gradient-boxen';

console.log(
  gradientBox(
    'I love gradients!',
    {
      borderStyle: 'round',
      padding: 1,
      margin: 1,
    },
    'fruit'
  )
);

Output:

These presets have been ported from gradient-string

🔮 API

gradientBox(boxText, boxOptions, gradientOptions)

boxText

Type: string

Text inside the box. Can be multiline too.

Warning All pre-existing ANSI colors are stripped from the text, so that the gradient can be properly displayed

boxOptions

Type: object

The configuration options for the box as per the boxen package

Options include:

{
  borderColor?: string
  borderStyle?: string
  dimBorder?: boolean
  padding?: number
  margin?: number
  float?: 'left' | 'right' | 'center'
  backgroundColor?: 'string'
  textAlignment?: 'left' | 'right' | 'center';
  title?: string
  titleAlignment?: 'left' | 'right' | 'center'
  width?: number
  height?: number
  fullscreen?: boolean
}

gradientOptions

Type: string or string[]

The gradient preset (or a set of gradients) to be used for the box. Can be a string or an array of valid color codes.

A list of presets can be found here

❤️ Support

You can support further development of this project by giving it a 🌟 and help me make even better stuff in the future by buying me a ☕

Also, if you liked this repo, consider checking out my other projects, that would be real cool!

💫 Attributions and special thanks

• boxen
• gradient-string