react-best-gradient-color-picker

The useColorPicker hook provides complete programmatic control over the picker. It allows you to access the current state (like which gradient point is selected) and manipulate the color values (like changing hue, saturation, or gradient type) without relying on the default UI. This is ideal for building custom UI controls that drive the picker.

import React, { useState } from 'react'
import ColorPicker, { useColorPicker } from 'react-best-gradient-color-picker'

function MyApp() {
  const [color, setColor] = useState('linear-gradient(90deg, rgba(96,93,93,1) 0%, rgba(255,255,255,1) 100%)');
  const { setSolid, setGradient } = useColorPicker(color, setColor);

  return(
    <div>
      <button onClick={setSolid}>Solid</button>
      <button onClick={setGradient}>Gradient</button>
      <ColorPicker value={color} onChange={setColor} />
    </div>
   )
}

Install the package using npm or yarn to use the customizable color and gradient picker in your React.js project.

npm install react-best-gradient-color-picker
# or
yarn add react-best-gradient-color-picker

To restrict the user to only selecting gradients, use the hideColorTypeBtns={true} prop and ensure the initial value is a gradient string. To restrict to only solid colors, do the inverse by providing a solid color as the initial value and hiding the gradient buttons.

// Only Gradients
<ColorPicker
  value="linear-gradient(90deg, rgba(96,93,93,1) 0%, rgba(255,255,255,1) 100%)"
  onChange={setColor}
  hideColorTypeBtns={true}
/>

Pass a locales object to the ColorPicker component to translate UI text. The object should follow the structure of the internal control keys (e.g., CONTROLS).

const customLocales = {
  CONTROLS: {
    SOLID: 'Obične',
    GRADIENT: 'Gradijent',
  },
}

<ColorPicker locales={customLocales} />

You can pass an array of color strings to the presets prop of the ColorPicker component. Note that the array is sliced to the first 18 colors if more are provided. You can also use previousColors from the useColorPicker hook to provide a history of recently used colors as presets.

// Using static presets
const customPresets = [
  'rgba(34, 164, 65, 1)',
  'rgba(210, 18, 40, .5)',
  // ... up to 18 colors
]

<ColorPicker value={color} onChange={setColor} presets={customPresets} />

// Using recently used colors from the hook
const { previousColors } = useColorPicker(color, setColor);
<ColorPicker value={color} onChange={setColor} presets={previousColors} />

The ColorPicker component is the primary UI element. It accepts a value (an rgba or CSS gradient string) and an onChange handler to update the state. This is the simplest way to integrate the picker into your application.

import React, { useState } from 'react'
import ColorPicker from 'react-best-gradient-color-picker'

function MyApp() {
  const [color, setColor] = useState('rgba(255,255,255,1)');

  return <ColorPicker value={color} onChange={setColor} />
}

The ColorPicker returns a CSS string via onChange. To get a structured JavaScript object representing the gradient (including type, degrees, and color stops), use the getGradientObject function from the useColorPicker hook.

const { getGradientObject } = useColorPicker(color, setColor);
const gradientObject = getGradientObject();

// Resulting object structure:
// {
//   "isGradient": true,
//   "gradientType": "linear-gradient",
//   "degrees": "40deg",
//   "colors": [
//       { "value": "rgba(27,107,235,1)", "left": 0 },
//       { "value": "rgba(25,245,157,1)", "left": 100 }
//     ]
// }

The useColorPicker hook provides access to the current internal state of the picker:

The useColorPicker hook provides utility functions to convert the current color state into various formats like HSL, HSV, Hex, and CMYK, as well as providing raw RGBA or HSL arrays.

import React, { useState } from 'react'
import ColorPicker, { useColorPicker } from 'react-best-gradient-color-picker'

function MyApp() {
  const [color, setColor] = useState('linear-gradient(90deg, rgba(96,93,93,1) 0%, rgba(255,255,255,1) 100%)');
  const { 
    valueToHSL, 
    valueToHSV, 
    valueToHex, 
    valueToCmyk, 
    rgbaArr, 
    hslArr 
  } = useColorPicker(color, setColor);

  const hslString = valueToHSL();
  const hsvString = valueToHSV();
  const hexString = valueToHex();
  const cmykString = valueToCmyk();
  const rgbaArray = rgbaArr;
  const hslArray = hslArr;

  return <ColorPicker value={color} onChange={setColor} />
}

The PassedConfig object allows you to pass specific configuration values into the component via the config prop in ColorPickerProps.

export type PassedConfig = {
  barSize?: number
  crossSize?: number
  defaultColor?: string
  defaultGradient?: string
}