tessl/npm-react-colorful
A tiny, lightweight color picker component library for React and Preact applications
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-react-colorful@5.6.0index.mddocs/
React Colorful
React Colorful is a tiny (2.8 KB), lightweight color picker component library for React and Preact applications. It offers a comprehensive collection of color picker components supporting multiple color formats (HEX, RGB, RGBA, HSL, HSLA, HSV, HSVA) along with their string representations. The library is designed with performance and accessibility in mind, featuring zero dependencies, TypeScript support, and WAI-ARIA compliance.
Package Information
- Package Name: react-colorful
- Package Type: npm
- Language: TypeScript
- Installation:
npm install react-colorful - Peer Dependencies: React >=16.8.0, React DOM >=16.8.0
Core Imports
import { HexColorPicker, RgbColorPicker, HslColorPicker } from "react-colorful";For CommonJS:
const { HexColorPicker, RgbColorPicker, HslColorPicker } = require("react-colorful");Tree-shakeable imports (recommended):
import { HexColorPicker } from "react-colorful";
import { RgbaColorPicker } from "react-colorful";
import { HexColorInput } from "react-colorful";Basic Usage
import React, { useState } from "react";
import { HexColorPicker } from "react-colorful";
const ColorPickerApp = () => {
const [color, setColor] = useState("#aabbcc");
return (
<div>
<HexColorPicker color={color} onChange={setColor} />
<p>Selected color: {color}</p>
</div>
);
};Architecture
React Colorful is built around several key components:
- Color Picker Components: 15 components for different color formats (basic, alpha channel, string formats)
- Input Components: Text input with validation for hexadecimal colors
- Type System: Complete TypeScript interfaces for all color formats and component props
- Color Models: Internal conversion system between different color representations
- CSP Support: Content Security Policy compliance via nonce utilities
Capabilities
Basic Color Pickers
Color pickers for basic color formats without alpha channel support.
/**
* Color picker for hexadecimal color values (6-digit format)
* @param props - ColorPickerBaseProps with string color type
*/
function HexColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
/**
* Color picker for RGB color objects
* @param props - ColorPickerBaseProps with RgbColor type
*/
function RgbColorPicker(props: Partial<ColorPickerBaseProps<RgbColor>>): JSX.Element;
/**
* Color picker for HSL color objects
* @param props - ColorPickerBaseProps with HslColor type
*/
function HslColorPicker(props: Partial<ColorPickerBaseProps<HslColor>>): JSX.Element;
/**
* Color picker for HSV color objects
* @param props - ColorPickerBaseProps with HsvColor type
*/
function HsvColorPicker(props: Partial<ColorPickerBaseProps<HsvColor>>): JSX.Element;Usage Examples:
import { HexColorPicker, RgbColorPicker, HslColorPicker } from "react-colorful";
// Hex color picker
<HexColorPicker color="#ff6b6b" onChange={setHexColor} />
// RGB color picker
<RgbColorPicker
color={{ r: 255, g: 107, b: 107 }}
onChange={setRgbColor}
/>
// HSL color picker
<HslColorPicker
color={{ h: 0, s: 75, l: 71 }}
onChange={setHslColor}
/>Alpha Channel Color Pickers
Color pickers that include alpha (transparency) channel support.
/**
* Color picker for hexadecimal colors with alpha (8-digit format)
* @param props - ColorPickerBaseProps with string color type
*/
function HexAlphaColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
/**
* Color picker for RGBA color objects
* @param props - ColorPickerBaseProps with RgbaColor type
*/
function RgbaColorPicker(props: Partial<ColorPickerBaseProps<RgbaColor>>): JSX.Element;
/**
* Color picker for HSLA color objects
* @param props - ColorPickerBaseProps with HslaColor type
*/
function HslaColorPicker(props: Partial<ColorPickerBaseProps<HslaColor>>): JSX.Element;
/**
* Color picker for HSVA color objects
* @param props - ColorPickerBaseProps with HsvaColor type
*/
function HsvaColorPicker(props: Partial<ColorPickerBaseProps<HsvaColor>>): JSX.Element;Usage Examples:
import { HexAlphaColorPicker, RgbaColorPicker } from "react-colorful";
// Hex with alpha
<HexAlphaColorPicker color="#ff6b6b80" onChange={setHexAlphaColor} />
// RGBA color picker
<RgbaColorPicker
color={{ r: 255, g: 107, b: 107, a: 0.5 }}
onChange={setRgbaColor}
/>String Format Color Pickers
Color pickers that work with CSS string representations of colors.
/**
* Color picker for RGB color strings (e.g., "rgb(255, 107, 107)")
* @param props - ColorPickerBaseProps with string color type
*/
function RgbStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
/**
* Color picker for RGBA color strings (e.g., "rgba(255, 107, 107, 0.5)")
* @param props - ColorPickerBaseProps with string color type
*/
function RgbaStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
/**
* Color picker for HSL color strings (e.g., "hsl(0, 75%, 71%)")
* @param props - ColorPickerBaseProps with string color type
*/
function HslStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
/**
* Color picker for HSLA color strings (e.g., "hsla(0, 75%, 71%, 0.5)")
* @param props - ColorPickerBaseProps with string color type
*/
function HslaStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
/**
* Color picker for HSV color strings (e.g., "hsv(0, 58%, 100%)")
* @param props - ColorPickerBaseProps with string color type
*/
function HsvStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
/**
* Color picker for HSVA color strings (e.g., "hsva(0, 58%, 100%, 0.5)")
* @param props - ColorPickerBaseProps with string color type
*/
function HsvaStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;Color Input Components
Text input components with validation for color values.
/**
* Text input for hexadecimal color values with validation
* @param props - HexColorInputProps including validation options
*/
function HexColorInput(props: HexColorInputProps): JSX.Element;
interface HexColorInputProps extends ColorInputBaseProps {
/** Current hex color value (optional) */
color?: string;
/** Color change callback (optional) */
onChange?: (newColor: string) => void;
/** Enables "#" prefix displaying */
prefixed?: boolean;
/** Allows #rgba and #rrggbbaa color formats */
alpha?: boolean;
}Usage Examples:
import { HexColorInput } from "react-colorful";
// Basic hex input
<HexColorInput color={color} onChange={setColor} />
// With prefix display
<HexColorInput color={color} onChange={setColor} prefixed />
// With alpha support
<HexColorInput color={color} onChange={setColor} alpha />Content Security Policy Support
Utility functions for CSP compliance in applications with strict content security policies.
/**
* Signs style tags with a base64-encoded nonce for CSP compliance
* Must be called before any picker is rendered if not using Webpack for CSP
* @param hash - Base64-encoded nonce string
*/
function setNonce(hash: string): void;Usage Example:
import { setNonce } from "react-colorful";
// Set nonce before rendering any color pickers
setNonce("your-csp-nonce-here");Types
Color Object Interfaces
/** RGB color representation with red, green, blue values (0-255) */
interface RgbColor {
r: number;
g: number;
b: number;
}
/** RGBA color representation extending RGB with alpha (0-1) */
interface RgbaColor extends RgbColor {
a: number;
}
/** HSL color representation with hue (0-360), saturation (0-100), lightness (0-100) */
interface HslColor {
h: number;
s: number;
l: number;
}
/** HSLA color representation extending HSL with alpha (0-1) */
interface HslaColor extends HslColor {
a: number;
}
/** HSV color representation with hue (0-360), saturation (0-100), value (0-100) */
interface HsvColor {
h: number;
s: number;
v: number;
}
/** HSVA color representation extending HSV with alpha (0-1) */
interface HsvaColor extends HsvColor {
a: number;
}
/** Union type of all color object types */
type ObjectColor = RgbColor | HslColor | HsvColor | RgbaColor | HslaColor | HsvaColor;
/** Union type of string and object color types */
type AnyColor = string | ObjectColor;Component Props Interfaces
/** Base props for color picker components */
interface ColorPickerBaseProps<T extends AnyColor> extends Omit<React.HTMLAttributes<HTMLDivElement>, "color" | "onChange" | "onChangeCapture"> {
/** Current color value */
color: T;
/** Color change callback */
onChange: (newColor: T) => void;
}
/** Base props for color input components */
interface ColorInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "onChange" | "value"> {
/** Current color value (optional) */
color?: string;
/** Color change callback (optional) */
onChange?: (newColor: string) => void;
}Internal Color Model Interface
/** Color model configuration interface (internal use) */
interface ColorModel<T extends AnyColor> {
defaultColor: T;
toHsva: (defaultColor: T) => HsvaColor;
fromHsva: (hsva: HsvaColor) => T;
equal: (first: T, second: T) => boolean;
}Color Value Formats
Supported Input/Output Formats by Component
- HexColorPicker:
"#ffffff"(6-digit hex) - HexAlphaColorPicker:
"#ffffff88"(8-digit hex with alpha) - RgbColorPicker:
{ r: 255, g: 255, b: 255 } - RgbaColorPicker:
{ r: 255, g: 255, b: 255, a: 1 } - RgbStringColorPicker:
"rgb(255, 255, 255)" - RgbaStringColorPicker:
"rgba(255, 255, 255, 1)" - HslColorPicker:
{ h: 0, s: 0, l: 100 } - HslaColorPicker:
{ h: 0, s: 0, l: 100, a: 1 } - HslStringColorPicker:
"hsl(0, 0%, 100%)" - HslaStringColorPicker:
"hsla(0, 0%, 100%, 1)" - HsvColorPicker:
{ h: 0, s: 0, v: 100 } - HsvaColorPicker:
{ h: 0, s: 0, v: 100, a: 1 } - HsvStringColorPicker:
"hsv(0, 0%, 100%)" - HsvaStringColorPicker:
"hsva(0, 0%, 100%, 1)"
Key Features
- Tree-shakeable: All components can be imported individually to reduce bundle size
- TypeScript support: Complete type definitions for all components and color formats
- Accessibility: WAI-ARIA compliant with keyboard navigation and screen reader support
- Mobile-friendly: Touch screen support with responsive design
- Zero dependencies: No external runtime dependencies
- Lightweight: Only 2.8 KB gzipped
- CSP compatible: Content Security Policy support via setNonce utility
- Cross-browser compatibility: Supports all modern browsers
- Framework agnostic: Works with both React and Preact