JavaScript Color Gradient Generator

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax in a CommonJS environment (e.g., a Node.js script without 'type: module' in package.json, or an older browser without transpilation/bundling).
  fix For Node.js, ensure your `package.json` includes `"type": "module"`. For browser environments, use a bundler (Webpack, Rollup, Parcel) to transpile the module, or serve it in a `<script type="module">` tag. Alternatively, consider dynamic `import()` for specific use cases.

• TypeError: Gradient is not a constructor

  cause This error typically occurs if `Gradient` is undefined or not correctly imported/exposed. This could be due to a faulty import, or attempting to use a CommonJS `require` in an ESM-only context.
  fix Verify that `import Gradient from 'javascript-color-gradient'` is correctly placed at the top of your ES module file. Ensure the file itself is treated as an ES module. If using CommonJS for other reasons, dynamic `import()` might be an option.

• TypeError: this.setColorGradient is not a function

  cause You are attempting to call `setColorGradient` on an object that is not an instance of the `Gradient` class, likely because the `new Gradient()` part of the chain was omitted or executed incorrectly.
  fix Always instantiate the `Gradient` class using `new Gradient()` before calling its methods. The correct pattern is `new Gradient().setColorGradient(...)`.

• Error: Invalid color value provided

  cause One or more of the color strings passed to the `setColorGradient` method is not a valid hexadecimal color code (e.g., missing '#', incorrect length, invalid characters).
  fix Double-check all color strings passed to `setColorGradient`. Ensure they are valid hex codes, starting with `#`, and either 3 or 6 hexadecimal characters long (e.g., `#FFF`, `#RRGGBB`).

Warnings

• breaking The gradient color generation logic was refactored in v2.5.0. While intended as an improvement, it might introduce subtle changes in the interpolated color values.
  Fix: Review the output of `getColors()` and `getColor()` if upgrading from versions prior to 2.5.0, as the interpolation might have changed. Adjust any tests that rely on exact color outputs.
• breaking The library's initialization method became more intuitive in v2.3.2, moving towards chained method calls (e.g., `new Gradient().setColorGradient(...)`). Older, direct constructor parameter patterns might be deprecated or no longer supported.
  Fix: Always use the chained method approach for initialization: `new Gradient().setColorGradient(...).setMidpoint(...)`. Avoid passing colors or midpoints directly to the `Gradient` constructor.
• gotcha Prior to v2.5.0, there was a bug where the first color in the gradient might have been skipped from the output array returned by `getColors()`.
  Fix: Upgrade to v2.5.0 or later to ensure all specified colors are correctly included in the gradient output array, especially the initial color.
• gotcha Short hex codes (e.g., `#fff`) were not supported before v2.5.0; only full 6-digit hex codes (e.g., `#ffffff`) were accepted.
  Fix: Upgrade to v2.5.0 or later to utilize short hex codes. For older versions, ensure all color inputs are provided as full 6-digit hexadecimal strings.
• gotcha The library is written using ES6 syntax (e.g., `import`/`export`). Older browser environments or Node.js versions without full ES module support may require transpilation (e.g., Babel) or different module loading configurations.
  Fix: Ensure your project's build process or runtime environment natively supports ES Modules, or include a transpilation step to convert the module to a compatible format for your target environment.

Install

• npm install javascript-color-gradient npm
• yarn add javascript-color-gradient yarn
• pnpm add javascript-color-gradient pnpm

Imports

• Gradient
  wrong:

  const Gradient = require('javascript-color-gradient')

  correct:

  import Gradient from 'javascript-color-gradient'

  The library primarily uses ES modules (ESM). CommonJS `require()` may not work as expected in newer versions without specific transpilation or Node.js 'type: module' configuration.
• Gradient (dynamic)

  const { default: Gradient } = await import('javascript-color-gradient')

  For dynamic ESM imports in environments that support it, or when mixing with CommonJS contexts.

Quickstart

Demonstrates how to initialize a gradient with two colors and retrieve an array of 10 interpolated hex color values.

import Gradient from "javascript-color-gradient";

const startColor = "#3F2CAF";
const endColor = "#e9446a";
const numberOfMidpoints = 10; // Default if not set

const gradientGenerator = new Gradient();
const gradientArray = gradientGenerator
  .setColorGradient(startColor, endColor)
  .setMidpoint(numberOfMidpoints) // Explicitly setting, though it's the default
  .getColors();

console.log(gradientArray);
/* Example output:
[
  '#3f2caf', '#522fa7',
  '#6531a0', '#783498',
  '#8b3790', '#9d3989',
  '#b03c81', '#c33f79',
  '#d64172', '#e9446a'
]
*/