React Iro Gradient Picker

✨ Modern React Color Picker with Complete Dark Theme Support! ✨

A beautiful, modern React gradient and solid color picker with full dark theme integration, built with Tailwind CSS and TypeScript.

🚀 ✨ LIVE DEMO & DOCUMENTATION ✨

📚 Interactive Documentation | 📦 NPM Package | 🔧 GitHub Repository

Inspired by gpickr and enhanced with modern features

✨ Features

• 🌙 Complete Dark Theme - Works perfectly across all components (modal, solid, gradient)
• 🎨 Gradient & Solid Colors - Full support for both gradient and solid color picking
• 🔄 Reset Button - Built-in reset functionality with customizable callbacks
• 🔄 Theme Toggle - Easy switching between light and dark themes
• 💾 Theme Persistence - Automatically saves user theme preference
• 🎯 Tailwind CSS - Modern styling with comprehensive theming system
• 📱 Responsive Design - Works great on all screen sizes

🎬 Live Demo

🚀 ✨ Try it Live - Interactive Storybook Demo ✨

Experience all features in action:

• 🌙 Dark/Light Theme Toggle - Switch themes and see all components adapt
• 🎨 Solid Color Picker - Pick any solid color with alpha transparency
• 🌈 Gradient Picker - Create linear/radial gradients with multiple stops
• 🔄 Dual Mode - Switch between solid and gradient modes seamlessly
• 📱 Responsive Design - Works perfectly on desktop and mobile
• ⚙️ All Props & Configuration - Explore every feature and customization option

📚 View Complete Documentation →

🚀 Quick Start

Install

Important: this component uses React Hooks and works on React version 16.8.0 and higher

npm install react-iro-gradient-picker

yarn add react-iro-gradient-picker

pnpm add react-iro-gradient-picker

⚠️ IMPORTANT: Import CSS Styles

You MUST import the CSS file for the component to work properly:

import 'react-iro-gradient-picker/dist/index.css';

Add this import at the top of your main App.js/App.tsx file or in your main CSS/SCSS file.

Basic Usage

import React, { useState } from 'react';
import ColorPicker from 'react-iro-gradient-picker';
import 'react-iro-gradient-picker/dist/index.css'; // ⚠️ REQUIRED CSS import

function App() {
  const [color, setColor] = useState('#3B82F6');

  return (
    <ColorPicker
      solid
      value={color}
      onChange={(newColor: string) => {
        setColor(newColor);
        return newColor;
      }}
    />
  );
}

export default App;

🔄 With Reset Functionality

import React, { useState } from 'react';
import ColorPicker from 'react-iro-gradient-picker';
import 'react-iro-gradient-picker/dist/index.css'; // ⚠️ REQUIRED CSS import

function App() {
  const [color, setColor] = useState('#3B82F6');
  const originalColor = '#3B82F6';

  const handleReset = () => {
    setColor(originalColor);
    console.log('Color reset to original value!');
  };

  return (
    <ColorPicker
      solid
      value={color}
      onChange={setColor}
      showReset
      onReset={handleReset}
    />
  );
}

export default App;

� NEW: Enhanced Gradient Object Support

v1.2.0+ supports both CSS strings AND gradient objects for maximum flexibility!

import React, { useState } from 'react';
import ColorPicker from 'react-iro-gradient-picker';
import 'react-iro-gradient-picker/dist/index.css';

function GradientObjectExample() {
  // Define gradient as an object
  const [gradientData, setGradientData] = useState({
    type: 'linear',
    angle: 120,
    stops: [
      { color: '#FF6B6B', position: 0 }, // Red at 0%
      { color: '#FFD93D', position: 50 }, // Yellow at 50%
      { color: '#6BCB77', position: 100 } // Green at 100%
    ]
  });

  return (
    <ColorPicker
      value={gradientData} // 🎯 Pass object directly!
      onChange={(cssGradient) => {
        console.log('Generated CSS:', cssGradient);
        // Component auto-switches to gradient tab
        // Sets angle to 120°, creates 3 stops with exact colors/positions
      }}
      gradient={true}
      solid={true}
      showGradientAngle={true}
      showGradientStops={true}
    />
  );
}

🚀 What happens when you pass a gradient object:

• ✅ Auto-switches to gradient tab
• ✅ Sets angle slider to specified degrees (120° in example)
• ✅ Creates gradient stops at exact positions (0%, 50%, 100%)
• ✅ Sets stop colors to specified values (#FF6B6B, #FFD93D, #6BCB77)
• ✅ Updates gradient preview to match exactly
• ✅ Returns CSS gradient string in onChange callback

📋 Gradient Object Structure:

interface IGradientData {
  type: 'linear' | 'radial';
  angle?: number; // For linear gradients (0-360 degrees)
  stops: Array<{
    color: string; // Any valid CSS color
    position: number; // 0-100 (percentage)
  }>;
}

�🌙 With Dark Theme Support

import React, { useState } from 'react';
import ColorPicker from 'react-iro-gradient-picker';
import { ThemeProvider } from 'react-iro-gradient-picker/components/providers/ThemeContext';

function App() {
  const [color, setColor] = useState('#3B82F6');

  return (
    <ThemeProvider defaultTheme='dark'>
      <ColorPicker
        solid
        gradient
        value={color}
        onChange={setColor}
        showAlpha={true}
        showInputs={true}
      />
    </ThemeProvider>
  );
}

🎨 Format Control

Control the color format returned by the onChange callback:

import React, { useState } from 'react';
import ColorPicker from 'react-iro-gradient-picker';

function FormatExample() {
  const [color, setColor] = useState('#3B82F6');

  // RGB format (default)
  <ColorPicker
    solid
    value={color}
    onChange={setColor}
    format="rgb"      // Returns: "rgb(59, 130, 246)" or "rgba(59, 130, 246, 0.8)"
  />

  // HSL format
  <ColorPicker
    solid
    value={color}
    onChange={setColor}
    format="hsl"      // Returns: "hsl(217, 91%, 60%)" or "hsla(217, 91%, 60%, 0.8)"
  />

  // HEX format
  <ColorPicker
    solid
    value={color}
    onChange={setColor}
    format="hex"      // Returns: "#3b82f6" or "#3b82f680" (with alpha)
  />
}

📚 → View Complete Documentation & Examples

🌟 What Makes This Special

This is an enhanced version of the original react-gcolor-picker with major improvements:

🌙 Complete Dark Theme Integration

• Fixed all components - Modal, solid picker, gradient picker, and inputs now work perfectly in dark mode
• CSS Custom Properties - Dynamic theming that responds to theme changes
• Tailwind CSS Integration - Modern, maintainable styling system
• Theme Toggle Component - Easy switching between light/dark themes
• Persistent Preferences - Automatically saves user's theme choice

🎯 Enhanced Storybook Documentation

• Dark-themed Storybook - Professional development environment
• Comprehensive Documentation - Updated guides and examples
• Live Examples - See all components working in both themes

🚀 Modern Development Stack

• TypeScript Support - Full type safety and better development experience
• Updated Dependencies - Latest versions of all packages
• Better Build Process - Optimized for modern React applications

🎨 Supported CSS Gradient Formats

v1.2.2+ supports all standard CSS gradient formats with robust parsing:

Linear Gradients

/* Angle-based directions */
linear-gradient(120deg, #FF6B6B, #FFD93D, #6BCB77)
linear-gradient(45deg, #4FACFE, #00F2FE, #38EF7D)
linear-gradient(200deg, #FF9A9E, #FAD0C4, #FBC2EB)
linear-gradient(60deg, #30CFD0, #330867, #6A82FB)

/* Named directions */
linear-gradient(to top right, #FF6B6B, #FFD93D)
linear-gradient(to bottom, #4FACFE, #00F2FE)
linear-gradient(to left, #FF9A9E, #FAD0C4)

/* With explicit positions */
linear-gradient(90deg, #FF6B6B 0%, #FFD93D 50%, #6BCB77 100%)

/* Without positions (auto-distributed) */
linear-gradient(180deg, #FF9966, #FF5E62, #F54EA2)

Radial Gradients

/* Basic circle gradients */
radial-gradient(circle at center, #00C9FF, #92FE9D, #0061FF)
radial-gradient(circle at top left, #FF6B6B, #FF4757, #2F3542)
radial-gradient(circle at bottom right, #1E90FF, #3742FA, #2C3E50)

/* Positioned radial gradients */
radial-gradient(circle at 70% 30%, #2ED573, #1EAE98, #004E64)
radial-gradient(circle at 20% 80%, #FFB347, #FFCC33, #FF6347)
radial-gradient(circle at top center, #FF7E5F, #FEB47B, #FFD93D)
radial-gradient(circle at right center, #6A82FB, #FC5C7D, #FF85A1)

/* Complex positioning */
radial-gradient(circle at 30% 70%, #11998E, #38EF7D, #8BC34A)
radial-gradient(circle at 80% 20%, #F7971E, #FFD200, #FF512F)
radial-gradient(circle at 40% 40%, #C6FFDD, #FBD786, #F7797D)

Advanced Features

• Auto-positioning: Color stops without explicit positions are automatically distributed evenly
• Flexible syntax: Supports various positioning keywords and percentage values
• Error recovery: Invalid gradients fall back to a default gradient instead of crashing
• Type safety: Full TypeScript support with proper gradient object interfaces

Props

When passing a value for a gradient, you must specify the position of all colors. Otherwise the component will throw an exception. For example:

Wrong

linear-gradient(180deg, #000000,#ff0000)

Correct

linear-gradient(180deg, #000000 0%,#ff0000 100%)

If you are using a radial gradient a list of possible directions for it:

circle at left top
circle at center top
circle at right top
circle at left
circle at center
circle at right
circle at left bottom
circle at center bottom
circle at right bottom

Default color list

'#FF6900',
'#FCB900',
'#7BDCB5',
'#00D084',
'#8ED1FC',
'#0693E3',
'#ABB8C3',
'#607d8b',
'#EB144C',
'#F78DA7',
'#ba68c8',
'#9900EF',
'linear-gradient(0deg, rgb(255, 177, 153) 0%, rgb(255, 8, 68) 100%)',
'linear-gradient(270deg, rgb(251, 171, 126) 8.00%, rgb(247, 206, 104) 92.00%)',
'linear-gradient(315deg, rgb(150, 230, 161) 8.00%, rgb(212, 252, 121) 92.00%)',
'linear-gradient(to left, rgb(249, 240, 71) 0%, rgb(15, 216, 80) 100%)',
'linear-gradient(315deg, rgb(194, 233, 251) 8.00%, rgb(161, 196, 253) 92.00%)',
'linear-gradient(0deg, rgb(0, 198, 251) 0%, rgb(0, 91, 234) 100%)',
'linear-gradient(0deg, rgb(167, 166, 203) 0%, rgb(137, 137, 186) 51.00%, rgb(137, 137, 186) 100%)',
'linear-gradient(0deg, rgb(80, 82, 133) 0%, rgb(88, 94, 146) 15.0%, rgb(101, 104, 159) 28.00%, rgb(116, 116, 176) 43.00%, rgb(126, 126, 187) 57.00%, rgb(131, 137, 199) 71.00%, rgb(151, 149, 212) 82.00%, rgb(162, 161, 220) 92.00%, rgb(181, 174, 228) 100%)',
'linear-gradient(270deg, rgb(255, 126, 179) 0%, rgb(255, 117, 140) 100%)',
'linear-gradient(90deg, rgb(120, 115, 245) 0%, rgb(236, 119, 171) 100%)',
'linear-gradient(45deg, #2e266f 0.00%, #9664dd38 100.00%)',
'radial-gradient(circle at center, yellow 0%, #009966 50%, purple 100%)'

FAQ

Q: There's any possibility to remove extra gradient lines?

A: Yes, you only need to drag them outside(bottom) the Gradient component area or double click on the element you want to remove.

Credits & Attribution

This project is based on the excellent react-gcolor-picker by undind, enhanced with:

• Complete dark theme integration
• Modern Tailwind CSS styling
• Improved TypeScript support
• Enhanced Storybook documentation
• Better accessibility features

Special thanks to the original author for creating such a solid foundation! 🙏

License

MIT © romfatal

Original project: MIT © undind