react-colorful

react-colorful is a color picker component for React (and Preact) applications that ships at roughly 2.8 KB gzipped with zero runtime dependencies. It provides ready-made picker components for every common color model — HEX, RGB(A), HSL(A), and HSV(A), both as objects and as CSS-formatted strings — so teams can drop in exactly the input/output shape their app already uses instead of writing conversion glue code themselves.

Beyond raw size, the library is built entirely with hooks and functional components, is tree-shakeable so unused pickers never reach the bundle, and follows WAI-ARIA guidelines for keyboard and screen-reader accessibility. It works out of the box on both mouse and touch devices, including inside iframes and Shadow DOM, making it a common default choice whenever a project needs a color picker without pulling in a heavier dependency like react-color.

What You Get

• Fourteen ready-to-use picker components covering HEX, HEX+alpha, RGB(A), HSL(A), and HSV(A) — both as structured objects and as CSS-formatted strings
• A standalone HexColorInput text field component that pairs with any picker for typed/pasted color entry, with optional # prefix and alpha support
• Full TypeScript typings shipped in the package itself, including exported types for each color model (e.g. HslColor, RgbaColor)
• Touch, mouse, keyboard, and screen-reader support out of the box, following WAI-ARIA guidelines
• Works correctly inside iframes and Shadow DOM via a setNonce utility and window-aware event handling
• Drop-in Preact compatibility through standard React-to-Preact aliasing

Common Use Cases

• Adding a color picker to a design-tool, theme editor, or CMS without inflating bundle size
• Building a custom color-input UI (e.g. a popover trigger) on top of the headless picker primitives
• Letting users type, paste, or copy a HEX value alongside the visual picker via HexColorInput
• Embedding a color picker inside an iframe-based editor or a Shadow DOM web component

Under The Hood

Architecture - Every picker component (e.g. HexColorPicker, RgbaColorPicker) is a thin wrapper around a shared ColorPicker in src/components/common/ColorPicker.tsx, which composes a Saturation panel and a Hue/Alpha slider on top of a common Interactive primitive (src/components/common/Interactive.tsx) that normalizes mouse and touch drag events into a single {left, top} coordinate. Internal state is always tracked in HSVA regardless of the public color format, via the useColorManipulation hook (src/hooks/useColorManipulation.ts), which converts incoming color props to HSVA, caches the last synced value in a ref to avoid update loops, and converts back to the target format before calling onChange/onChangeEnd. Each color-model-specific component (HEX, RGB, HSL, HSV, and their alpha/string variants) supplies its own ColorModel object (src/types.ts) with toHsva/fromHsva/equal functions, so adding or swapping a format is a matter of providing new conversion functions rather than touching the interaction logic.

Tech Stack - Written entirely in TypeScript with functional components and hooks (React 16.8+ and Preact are supported as peer dependencies, not bundled). The library has zero runtime dependencies, and styling is inlined via a useStyleSheet hook (src/hooks/useStyleSheet.ts) that injects CSS into the document rather than requiring a separate stylesheet import, with setNonce support for CSP-restricted environments. It’s built with microbundle, producing CJS, ESM, and UMD outputs plus bundled .d.ts types, and distributed at roughly 2.8 KB gzipped per bundlephobia.

Code Quality - The tests/ directory (778 lines across components.test.js and utils.test.js) exercises the public API with @testing-library/react, including synthetic mouse/touch event simulation (a custom FakeMouseEvent class) and dedicated coverage for CSP nonce handling (csp.test.js) and Shadow DOM rendering (shadowDom.test.js). Conversion utilities (src/utils/convert.ts) are pure functions with narrow, single-purpose helpers (clamp, round, compare), and the codebase consistently uses small, well-commented modules — e.g. useEventCallback.ts is an 11-line hook solving one specific problem (stale closures in callbacks) rather than pulling in a general-purpose library for it.

API Design - The public surface is deliberately minimal: every picker accepts just color, onChange, and an optional onChangeEnd, plus standard div props like className and style for styling hooks. Naming is consistent and predictable across all fourteen components (<Model><Alpha?><String?>ColorPicker), so once a developer learns one picker, the rest follow the same pattern with no additional documentation lookup required. The README documents every prop, supported color model, and customization path (CSS overrides, HexColorInput pairing) with runnable CodeSandbox links, keeping the barrier to a working integration very low.