# tinygradient

> Fast and small gradients manipulation, built on top of TinyColor

Latest version **2.0.1** (published 2025-02-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install tinygradient
pnpm add tinygradient
yarn add tinygradient
bun add tinygradient
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2025-02-18 |
| First published | 2014-06-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 20.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 243 |
| Author | Damien "Mistic" Sorel |
| Maintainers | mistic100 |
| Keywords | color, gradient |

## Links

- npm: https://www.npmjs.com/package/tinygradient
- Repository: https://github.com/mistic100/tinygradient
- Issues: https://github.com/mistic100/tinygradient/issues
- npm.io page: https://npm.io/package/tinygradient

## Dependencies (1)

- [tinycolor2](https://npm.io/package/tinycolor2.md) ^1.6.0

## Alternatives

- [postcss-color-hex-alpha](https://npm.io/package/postcss-color-hex-alpha.md) — 6.4M weekly downloads
- [randomcolor](https://npm.io/package/randomcolor.md) — 348.0K weekly downloads
- [bows](https://npm.io/package/bows.md) — 1.3K weekly downloads
- [ep_prefer_color_scheme](https://npm.io/package/ep_prefer_color_scheme.md) — 260 weekly downloads
- [coc-yank](https://npm.io/package/coc-yank.md) — 61 weekly downloads

## Recent versions

- 2.0.1 (latest) — 2025-02-18
- 2.0.0 — 2025-02-05
- 1.1.5 — 2021-06-05
- 1.1.4 — 2021-03-17
- 1.1.3 — 2021-02-22
- 1.1.2 — 2020-04-26
- 1.1.1 — 2020-01-13
- 1.1.0 — 2019-12-03
- 1.0.0 — 2019-01-01
- 0.4.3 — 2018-12-15
- 0.4.2 — 2018-10-30
- 0.4.1 — 2018-09-03
- 0.4.0 — 2018-04-11
- 0.3.1 — 2016-10-28
- 0.3.0 — 2014-12-13
- … 2 more at https://npm.io/package/tinygradient/versions

## README

# tinygradient

[![npm version](https://img.shields.io/npm/v/tinygradient.svg?style=flat-square)](https://www.npmjs.com/package/tinygradient)
[![jsDelivr CDN](https://data.jsdelivr.com/v1/package/npm/tinygradient/badge)](https://www.jsdelivr.com/package/npm/tinygradient)
[![GZIP size](https://img.shields.io/bundlephobia/minzip/tinygradient?label=gzip%20size)](https://bundlephobia.com/result?p=tinygradient)
[![Build Status](https://github.com/mistic100/tinygradient/workflows/CI/badge.svg)](https://github.com/mistic100/tinygradient/actions)

Easily generate color gradients with an unlimited number of color stops and steps. 

[Live demo](https://mistic100.github.io/tinygradient/)

## Installation

```
$ npm install tinygradient
```

### Dependencies

- [TinyColor](https://github.com/bgrins/TinyColor)

## Usage

The gradient can be generated using RGB or HSV interpolation. HSV usually produces brighter colors.

### Initialize gradient

The `tinygradient` constructor takes a list or an array of colors stops.

```javascript
// using varargs
const gradient = tinygradient('red', 'green', 'blue');

// using array
const gradient = tinygradient([
  '#ff0000',
  '#00ff00',
  '#0000ff'
]);
```

The colors are parsed with TinyColor, [multiple formats are accepted](https://github.com/bgrins/TinyColor/blob/master/README.md#accepted-string-input).

```javascript
const gradient = tinygradient([
  tinycolor('#ff0000'),       // 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
]);
```

You can also specify the position of each color stop (between `0` and `1`). If no position is specified, stops are distributed equidistantly.

```javascript
const gradient = tinygradient([
  {color: '#d8e0de', pos: 0},
  {color: '#255B53', pos: 0.8},
  {color: '#000000', pos: 1}
]);
```

### Generate gradient

Each method takes at least the number of desired steps.
> The generated gradients might have one more step in certain conditions.

```javascript
// RGB interpolation
const colorsRgb = gradient.rgb(9);
```
![rgb](https://raw.githubusercontent.com/mistic100/tinygradient/master/images/rgb.png)

```javascript
// HSV clockwise interpolation
const colorsHsv = gradient.hsv(9);
```
![hsv](https://raw.githubusercontent.com/mistic100/tinygradient/master/images/hsv.png)

```javascript
// HSV counter-clockwise interpolation
const colorsHsv = gradient.hsv(9, true);
```
![hsv2](https://raw.githubusercontent.com/mistic100/tinygradient/master/images/hsv2.png)

There are also two methods which will automatically choose between clockwise and counter-clockwise.

```javascript
// HSV interpolation using shortest arc between colors
const colorsHsv = gradient.hsv(9, 'short');

// HSV interpolation using longest arc between colors
const colorsHsv = gradient.hsv(9, 'long');
```

Each method returns an array of TinyColor objects, [see available methods](https://github.com/bgrins/TinyColor/blob/master/README.md#methods).

### Get CSS gradient string

The `css` method will output a valid W3C string (without vendors prefix) to use with `background-image` CSS property.

```javascript
// linear gradient to right (default)
const gradientStr = gradient.css();

// radial gradient ellipse at top left
const gradientStr = gradient.css('radial', 'farthest-corner ellipse at top left');
```

### Get color at a specific position

Returns a single TinyColor object from a defined position in the gradient (from 0 to 1).

```javascript
// with RGB interpolation
colorAt55Percent = gradient.rgbAt(0.55);

// with HSV interpolation
colorAt55Percent = gradient.hsvAt(0.55);
```

### Reversing gradient

Returns a new instance of TinyGradient with reversed colors.

```javascript
const reversedGradient = gradient.reverse();
```

### Loop the gradient

Returns a new instance of TinyGradient with looped colors.

```javascript
const loopedGradient = gradient.loop();
```

### Position-only stops

I is possible to define stops with the `pos` property only and no `color`. This allows to define the position of the mid-point between the previous and the next stop.

```js
const gradient = tinygradient([
  {color: 'black', pos: 0},
  {pos: 0.8}, // #808080 will be at 80% instead of 50%
  {color: 'white', pos: 1}
]);
```


## License
This library is available under the MIT license.

---
_Source: https://npm.io/package/tinygradient · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._