# 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](https://github.com/sindresorhus/boxen/) and [gradient-string](https://github.com/bokub/gradient-string) into one unified package.**
## 🛠️ Install
Using [npm](https://www.npmjs.com/)
```text
npm i gradient-boxen
```
> **Note**
> This package is ESM only. Please check out [this guide](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) on how to convert your project to ESM
---
## 🔗 Usage
> **Note**
> This package will properly display gradient boxes only in terminals with [TrueColor](https://en.wikipedia.org/wiki/Color_depth#True_color_(24-bit)) 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
```js
import gradientBox from 'gradient-boxen';
console.log(
gradientBox(
'I love gradients!',
{
borderStyle: 'round',
padding: 1,
margin: 1,
},
['#11998e', '#38ef7d']
)
);
```
Output:
- Using a predefined preset
```js
import gradientBox from 'gradient-boxen';
console.log(
gradientBox(
'I love gradients!',
{
borderStyle: 'round',
padding: 1,
margin: 1,
},
'fruit'
)
);
```
Output:
List of available presets
These presets have been ported from [gradient-string](https://github.com/bokub/gradient-string#available-built-in-gradients)
---
## 🔮 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](https://github.com/sindresorhus/boxen#options) package
Options include:
```js
{
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](https://github.com/bokub/gradient-string#available-built-in-gradients)
---
## ❤️ 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](https://github.com/sindresorhus/boxen/)
- [gradient-string](https://github.com/bokub/gradient-string)