Narcissistic Preening Monarch
    Have ideas to improve npm?Join in the discussion! »

    gradient-string
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/gradient-string package

    1.2.0 • Public • Published

    gradient-string

    Build Status Version Codecov Downloads XO code style Mentioned in Awesome Node.js

    Beautiful color gradients in terminal output

    gradient-string

    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

    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

    Example result

    Typescript

    Typescript definitions of gradient-string are available on DefinitelyTyped

    npm i @types/gradient-string

    Dependencies

    License

    MIT © Boris K

    Install

    npm i gradient-string

    DownloadsWeekly Downloads

    19,789

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    11.1 kB

    Total Files

    4

    Last publish

    Collaborators

    • avatar