gradient-string
Beautiful color gradients in terminal output
Install
$ npm i gradient-string
Usage
const gradient = require('gradient-string');
console.log(gradient('cyan', 'pink')('Hello world!'));
Initialize a gradient
// Using varargs
let coolGradient = gradient('red', 'green', 'blue');
// Using array
let coolGradient = gradient(['#FF0000', '#00FF00', '#0000FF']);
The colors are parsed with TinyColor, multiple formats are accepted.
let coolGradient = gradient([
tinycolor('#FFBB65'), // tinycolor object
{r: 0, g: 255, b: 0}, // RGB object
{h: 240, s: 1, v: 1, a: 1}, // HSVa object
'rgb(120, 120, 0)', // RGB CSS string
'gold' // named color
]);
Use a gradient
let coolString = coolGradient('This is a fancy string!');
console.log(coolString);
Built-in gradients
Usage
const gradient = require('gradient-string');
// Use the rainbow gradient
console.log(gradient.rainbow('I love gradient-strings!'))
Available built-in gradients
Multi line gradients
In some cases, you may want to apply the same horizontal gradient on each line of a long text (or a piece of ASCII art).
You can use the multiline() method of a gradient to ensure that the colors are vertically aligned.
const gradient = require('gradient-string');
// Use the same gradient on every line
let duck = gradient('orange', 'yellow').multiline([
" __",
"<(o )___",
" ( ._> /",
" `---'",
].join('\n'));
console.log(duck);
// Works with aliases
gradient.atlas.multiline('Multi line\nstring');
// Works with advanced options
gradient('cyan', 'pink').multiline('Multi line\nstring', {interpolation: 'hsv'});
Advanced gradients
There are also more advanced options for gradient customization, such as custom color stops, or choice of color interpolation
Custom color stops
By default, the gradient color stops are distributed equidistantly.
You can specify the position of each color stop (between 0 and 1), using the following syntax:
let coolGradient = gradient([
{color: '#d8e0de', pos: 0},
{color: '#255B53', pos: 0.8},
{color: '#000000', pos: 1}
]);
Color interpolation
When using a gradient, you can actually add a second parameter to choose how the colors will be generated.
Here is the full gradient API:
myGradient(text, [options])
text
Type: string
String you want to color.
options
Type: Object
interpolation
Type: string
The gradient can be generated using RGB or HSV interpolation. HSV usually produces brighter colors. interpolation can be set to rgb for RGB interpolation, orhsv for HSV interpolation.
Defaults to rgb. Case insentitive
hsvSpin
Type: string
Used only in the case of HSV interpolation.
Because hue can be considered as a circle, there are two ways to go from a color to another color.
hsvSpin can be either short or long, depending on if you want to take the shortest or the longest way between two colors.
Defaults to short. Case insensitive
Example
Code
const redToGreen = gradient('red', 'green');
const str = '■'.repeat(48);
// Standard RGB gradient
console.log(redToGreen(str));
// Short HSV gradient: red -> yellow -> green
console.log(redToGreen(str, {interpolation: 'hsv'}));
// Long HSV gradient: red -> magenta -> blue -> cyan -> green
console.log(redToGreen(str, {interpolation: 'hsv', hsvSpin: 'long'}));
Result
Typescript
Typescript definitions of gradient-string are available on DefinitelyTyped
npm i @types/gradient-string
Dependencies
- tinygradient - Generate gradients
- chalk - Output colored text to terminal
License
MIT © Boris K
34 Jan 3, 2023
23 Feb 8, 2022
3 Nov 7, 2022
6.1k Jan 1, 2023
3.2k Dec 23, 2022
410 Dec 10, 2022
262 Nov 21, 2022
234 Jan 1, 2023
104 Mar 3, 2022
3.1k Jan 3, 2023