React Color Palette

https://github.com/wondermarin/react-color-palette
Admin
React Color Palette is a lightweight, customizable, and high-performance color picker component for...
Tokens:21,810
Snippets:274
Trust Score:6.7
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install react-color-palette

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/INDEX.md

Command to install the library via npm.

```bash
npm install react-color-palette
```

--------------------------------

### Install react-color-palette

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

Installation commands for yarn and npm package managers.

```sh
yarn add react-color-palette
```

```sh
npm install react-color-palette
```

--------------------------------

### Basic Hex Initialization

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-color.md

Example of initializing the hook with a hex color string.

```typescript
import { ColorPicker, useColor } from "react-color-palette";
import "react-color-palette/css";

export function App() {
  // Initialize with hex color
  const [color, setColor] = useColor("#561ecb");

  return (
    <div>
      <ColorPicker color={color} onChange={setColor} />
      <p>Current color: {color.hex}</p>
    </div>
  );
}
```

--------------------------------

### RGB Initialization

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-color.md

Example of initializing the hook with an RGB color string.

```typescript
import { ColorPicker, useColor } from "react-color-palette";
import "react-color-palette/css";

export function App() {
  // Initialize with RGB format
  const [color, setColor] = useColor("rgb(86 30 203 / 0.8)");

  return (
    <ColorPicker color={color} onChange={setColor} />
  );
}
```

--------------------------------

### Initialize IColorHsv objects

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/types.md

Examples of creating IColorHsv objects for various colors and transparency levels.

```typescript
// Pure red
const red: IColorHsv = { h: 0, s: 100, v: 100, a: 1 };

// Medium green
const mediumGreen: IColorHsv = { h: 120, s: 100, v: 50, a: 1 };

// Desaturated blue (grayish)
const grayishBlue: IColorHsv = { h: 240, s: 20, v: 80, a: 1 };

// Semi-transparent yellow
const semiTransparentYellow: IColorHsv = { h: 60, s: 100, v: 100, a: 0.5 };
```

--------------------------------

### isTouch Usage Examples

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/utilities.md

Demonstration of isTouch behavior with various event types.

```typescript
const mouseEvent = new MouseEvent("mousedown");
isTouch(mouseEvent); // false

const touchEvent = new TouchEvent("touchstart");
isTouch(touchEvent); // true

const reactMouseEvent = {...} as React.MouseEvent;
isTouch(reactMouseEvent); // false

const reactTouchEvent = {...} as React.TouchEvent;
isTouch(reactTouchEvent); // true
```

--------------------------------

### Saturation Component Usage

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/saturation.md

Example implementation showing how to integrate the Saturation component with the useColor hook.

```typescript
import { Saturation, useColor } from "react-color-palette";
import "react-color-palette/css";

export function ColorPickerCustom() {
  const [color, setColor] = useColor("hsl(120, 100%, 50%)");

  return (
    <div style={{ width: 300 }}>
      <Saturation 
        height={250}
        color={color} 
        onChange={setColor}
        onChangeComplete={(finalColor) => {
          console.log("Saturation/value selection done:", finalColor.hex);
        }}
      />
    </div>
  );
}
```

--------------------------------

### Named Color Initialization

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-color.md

Example of initializing the hook with a CSS named color.

```typescript
import { Saturation, Hue, useColor } from "react-color-palette";
import "react-color-palette/css";

export function CustomPicker() {
  // Initialize with named color
  const [color, setColor] = useColor("cyan");

  return (
    <div className="custom-layout">
      <Saturation height={300} color={color} onChange={setColor} />
      <Hue color={color} onChange={setColor} />
    </div>
  );
}
```

--------------------------------

### Usage of IColorRgb

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/types.md

Examples of creating RGB color objects and formatting them for CSS usage.

```typescript
// Creating an RGB color
const red: IColorRgb = { r: 255, g: 0, b: 0, a: 1 };

// Creating a semi-transparent blue
const semiTransparentBlue: IColorRgb = { r: 0, g: 0, b: 255, a: 0.5 };

// Converting to string for CSS
const cssRgb = `rgb(${red.r}, ${red.g}, ${red.b} / ${red.a})`;
// Output: "rgb(255, 0, 0 / 1)"
```

--------------------------------

### Hue Component Usage

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/hue.md

Example implementation of the Hue component with state management and interaction callbacks.

```typescript
import { Hue, useColor } from "react-color-palette";
import "react-color-palette/css";

export function ColorPickerCustom() {
  const [color, setColor] = useColor("#ff0000");

  return (
    <div style={{ width: 300, marginTop: 20 }}>
      <Hue 
        color={color} 
        onChange={setColor}
        onChangeComplete={(finalColor) => {
          console.log("Hue selection done:", finalColor.hex);
        }}
      />
    </div>
  );
}
```

--------------------------------

### Convert Colors Using ColorService

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Examples of converting hex, RGB, and HSV inputs into a full IColor object.

```typescript
// Convert from hex string
const color1 = ColorService.convert("hex", "#ff0000");
// Returns { hex: "#ff0000", rgb: { r: 255, g: 0, b: 0, a: 1 }, hsv: { h: 0, s: 100, v: 100, a: 1 } }

// Convert from RGB object
const color2 = ColorService.convert("rgb", { r: 0, g: 255, b: 0, a: 1 });
// Returns { hex: "#00ff00", rgb: { r: 0, g: 255, b: 0, a: 1 }, hsv: { h: 120, s: 100, v: 100, a: 1 } }

// Convert from HSV object
const color3 = ColorService.convert("hsv", { h: 240, s: 100, v: 100, a: 0.5 });
// Returns { hex: "#0000ff", rgb: { r: 0, g: 0, b: 255, a: 0.5 }, hsv: { h: 240, s: 100, v: 100, a: 0.5 } }
```

--------------------------------

### ColorPicker Usage Example

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-picker.md

Basic implementation of the ColorPicker component using the useColor hook for state management.

```typescript
import { ColorPicker, useColor } from "react-color-palette";
import "react-color-palette/css";

export function App() {
  const [color, setColor] = useColor("#561ecb");

  return (
    <ColorPicker 
      color={color} 
      onChange={setColor}
      onChangeComplete={(color) => {
        console.log("Color selection complete:", color.hex);
      }}
    />
  );
}
```

--------------------------------

### isFieldHide Logic Examples

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/utilities.md

Demonstrates how the function behaves with different boolean and array inputs.

```typescript
isFieldHide(true, "hex");           // true (hide all)
isFieldHide(false, "hex");          // false (show all)
isFieldHide(["rgb", "hsv"], "hex"); // false (hex not in array, show it)
isFieldHide(["rgb", "hsv"], "rgb"); // true (rgb in array, hide it)
isFieldHide([], "hex");             // false (empty array, show all)
```

--------------------------------

### Usage in ColorPicker Component

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/utilities.md

Example of using the utility to conditionally render an input field within a component.

```typescript
{!isFieldHide(hideInput, "hex") && (
  <div className="rcp-field">
    <input id="hex" {...props} />
  </div>
)}
```

--------------------------------

### isTouch Type Narrowing

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/utilities.md

Example of using isTouch to narrow event types for TypeScript.

```typescript
if (isTouch(event)) {
  const touch = event.touches[0]; // Now TypeScript knows 'touches' exists
}
```

--------------------------------

### Project File Structure

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/INDEX.md

Visual representation of the source directory layout.

```text
src/
├── rcp.ts                              # Entry point
├── components/
│   ├── color-picker/
│   │   ├── color-picker.component.tsx
│   │   └── index.ts
│   ├── saturation/
│   │   ├── saturation.component.tsx
│   │   └── index.ts
│   ├── hue/
│   │   ├── hue.component.tsx
│   │   └── index.ts
│   ├── alpha/
│   │   ├── alpha.component.tsx
│   │   └── index.ts
│   ├── fields/
│   │   ├── fields.component.tsx
│   │   └── index.ts
│   └── interactive/
│       ├── interactive.component.tsx
│       └── index.ts
├── hooks/
│   ├── use-color/
│   │   ├── use-color.hook.ts
│   │   └── index.ts
│   └── use-bounding-client-rect/
│       ├── use-bounding-client-rect.hook.ts
│       └── index.ts
├── services/
│   └── color/
│       ├── color.service.ts
│       └── index.ts
└── utils/
    ├── clamp/
    ├── float/
    ├── format/
    ├── is-field-hide/
    └── is-touch/
```

--------------------------------

### useColor(initialColor: string)

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-color.md

Initializes color state from a string and returns the state and a setter function.

```APIDOC
## useColor(initialColor: string)

### Description
Initializes a color state from a provided string and returns a tuple containing the current color object and a setter function.

### Signature
`function useColor(initialColor: string): [IColor, React.Dispatch<React.SetStateAction<IColor>>]`

### Parameters
- **initialColor** (string) - Required - A color string in supported formats (Hex, Named, RGB, HSL, HWB).

### Return Value
- **IColor** (object) - The current color state containing hex, rgb, and hsv representations.
- **Setter Function** (function) - A React dispatch function to update the color state, accepting either an IColor object or a functional update.
```

--------------------------------

### useColor()

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

A hook to manage color state.

```APIDOC
## useColor()

### Arguments
- **initialColor** (TColor) - Required - The initial color value.
```

--------------------------------

### Usage of IColor

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/types.md

Demonstrates initializing an IColor object and accessing its properties.

```typescript
const color: IColor = {
  hex: "#ff0000",
  rgb: { r: 255, g: 0, b: 0, a: 1 },
  hsv: { h: 0, s: 100, v: 100, a: 1 }
};

// Access different representations
console.log(color.hex);      // "#ff0000"
console.log(color.rgb.r);    // 255
console.log(color.hsv.h);    // 0
```

--------------------------------

### Color Initialization Flow

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/architecture.md

The process of initializing color state using the useColor hook and ColorService.

```text
useColor(colorString)
├── Parse with ColorService.convert("hex", colorString)
└── Return [IColor, setColor]
```

--------------------------------

### Create custom layout

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

Build a custom color picker interface using individual Saturation and Hue components.

```tsx
import { Saturation, Hue, useColor } from "react-color-palette";
import "react-color-palette/css";

export function App() {
  const [color, setColor] = useColor("hsl(120 100% 50% / .5)");

  return (
    <div className="custom-layout">
      <Saturation height={300} color={color} onChange={setColor} />
      <Hue color={color} onChange={setColor} />
    </div>
  );
}
```

--------------------------------

### <Saturation />

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

A standalone saturation selection component.

```APIDOC
## <Saturation />

### Props
- **height** (number) - Required - Height of the saturation element in pixels.
- **color** (IColor) - Required - Current color state.
- **disabled** (boolean) - Optional - Disables interactivity (default: false).
- **onChange** (Function) - Optional - Callback fired when color changes.
- **onChangeComplete** (Function) - Optional - Callback fired when interaction is complete.
```

--------------------------------

### <Hue />

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

A standalone hue selection component.

```APIDOC
## <Hue />

### Props
- **color** (IColor) - Required - Current color state.
- **disabled** (boolean) - Optional - Disables interactivity (default: false).
- **onChange** (Function) - Optional - Callback fired when color changes.
- **onChangeComplete** (Function) - Optional - Callback fired when interaction is complete.
```

--------------------------------

### Use RGB color format

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

Initialize the color picker with an RGB string value.

```tsx
import { ColorPicker, useColor } from "react-color-palette";
import "react-color-palette/css";

export function App() {
  const [color, setColor] = useColor("rgb(86 30 203)");

  return <ColorPicker color={color} onChange={setColor} />;
}
```

--------------------------------

### Format RGB for CSS

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/types.md

Demonstrates converting IColorRgb data into modern and legacy CSS string formats.

```typescript
const color = ColorService.convert("hex", "#ff0000");
const rgb = color.rgb;

// Modern CSS syntax (with alpha)
const cssModern = `rgb(${rgb.r} ${rgb.g} ${rgb.b} / ${rgb.a})`;

// Legacy CSS syntax (comma-separated)
const cssLegacy = `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${rgb.a})`;
```

--------------------------------

### Component Hierarchy

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/INDEX.md

Visual representation of the ColorPicker component structure.

```text
ColorPicker
├── Saturation → Interactive
├── Hue → Interactive
├── Alpha → Interactive
└── Fields
```

--------------------------------

### Create Custom Layout

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/getting-started.md

Use individual subcomponents to build a custom color picker interface.

```typescript
import { Saturation, Hue, Alpha, useColor } from "react-color-palette";
import "react-color-palette/css";

export function CustomPicker() {
  const [color, setColor] = useColor("hsl(120 100% 50% / .5)");

  return (
    <div className="custom-layout">
      <Saturation height={300} color={color} onChange={setColor} />
      <div className="controls">
        <Hue color={color} onChange={setColor} />
        <Alpha color={color} onChange={setColor} />
      </div>
    </div>
  );
}
```

--------------------------------

### Usage of useBoundingClientRect in Picker Components

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-bounding-client-rect.md

Demonstrates initializing the hook and using getPosition to calculate relative coordinates for color picking.

```typescript
// In Saturation component
const [saturationRef, { width }, getPosition] = useBoundingClientRect<HTMLDivElement>();

// ...in updateColor handler
const move = (event) => {
  const { left, top } = getPosition();
  const x = clamp(event.clientX - left, 0, width);
  const y = clamp(event.clientY - top, 0, height);
  
  onCoordinateChange(final, x, y);
};
```

--------------------------------

### Import and use IColor in custom interfaces

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/types.md

Demonstrates importing the IColor type to define structured color preferences in user code.

```typescript
import { type IColor } from "react-color-palette";

interface UserColorPreference {
  label: string;
  color: IColor;
}

const preferences: UserColorPreference[] = [
  { label: "Primary", color: { hex: "#0066ff", rgb: { r: 0, g: 102, b: 255, a: 1 }, hsv: { h: 210, s: 100, v: 100, a: 1 } } },
  { label: "Accent", color: { hex: "#ff6600", rgb: { r: 255, g: 102, b: 0, a: 1 }, hsv: { h: 30, s: 100, v: 100, a: 1 } } },
];
```

--------------------------------

### ColorService.toRgb(value: string)

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Parses an RGB format string into an RGB object.

```APIDOC
## ColorService.toRgb(value: string)

### Description
Parses an RGB format string into an RGB object. It extracts numeric values, clamps R, G, B to 0-255 and A to 0-1.

### Parameters
- **value** (string) - Required - The RGB color string to parse.

### Returns
- **Object** - An object containing { r, g, b, a }.
```

--------------------------------

### Use named color format

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

Initialize the color picker with a CSS named color string.

```tsx
import { ColorPicker, useColor } from "react-color-palette";
import "react-color-palette/css";

export function App() {
  const [color, setColor] = useColor("cyan");

  return <ColorPicker color={color} onChange={setColor} />;
}
```

--------------------------------

### Importing CSS Styles

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/getting-started.md

Include the library's stylesheet to apply default layout and styling to the color picker components.

```typescript
import "react-color-palette/css";
```

--------------------------------

### Library Exports

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/INDEX.md

Primary components, hooks, and services exported from the main entry point.

```typescript
export { ColorPicker } from "./components/color-picker";
export { Saturation } from "./components/saturation";
export { Hue } from "./components/hue";
export { Alpha } from "./components/alpha";
export { useColor } from "./hooks/use-color";
export { ColorService, type IColor } from "./services/color";
```

--------------------------------

### ColorService.toHsv(value: string)

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Parses an HSV/HSL format string into an HSV object.

```APIDOC
## ColorService.toHsv(value: string)

### Description
Parses an HSV/HSL format string into an HSV object. It extracts numeric values, clamps H to 0-360, S and V to 0-100, and A to 0-1.

### Parameters
- **value** (string) - Required - The HSV/HSL color string to parse.

### Returns
- **Object** - An object containing { h, s, v, a }.
```

--------------------------------

### <Alpha />

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

A standalone alpha (transparency) selection component.

```APIDOC
## <Alpha />

### Props
- **color** (IColor) - Required - Current color state.
- **disabled** (boolean) - Optional - Disables interactivity (default: false).
- **onChange** (Function) - Optional - Callback fired when color changes.
- **onChangeComplete** (Function) - Optional - Callback fired when interaction is complete.
```

--------------------------------

### <ColorPicker />

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

The main component that provides a full color picker interface including saturation, hue, alpha, and input fields.

```APIDOC
## <ColorPicker />

### Props
- **height** (number) - Optional - Height of the Saturation component in pixels (default: 200).
- **hideAlpha** (boolean) - Optional - Hides the Alpha component (default: false).
- **hideInput** ((keyof IColor)[] | boolean) - Optional - Hides specific or all inputs (default: false).
- **color** (IColor) - Required - Current color state.
- **disabled** (boolean) - Optional - Disables interactivity (default: false).
- **onChange** (Function) - Optional - Callback fired when color changes.
- **onChangeComplete** (Function) - Optional - Callback fired when interaction is complete.
```

--------------------------------

### Programmatic Color Updates

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-color.md

Demonstrates how to update the color state using direct values, functional updates, or converted formats.

```typescript
const [color, setColor] = useColor("#ff0000");

// Direct update
setColor(ColorService.convert("hex", "#00ff00"));

// Functional update
setColor(prev => ColorService.convert("hex", "#0000ff"));

// Update from other formats
setColor(ColorService.convert("rgb", { r: 255, g: 0, b: 0, a: 1 }));
```

--------------------------------

### ResizeObserver implementation

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-bounding-client-rect.md

The hook uses ResizeObserver within useLayoutEffect to track element-level size changes.

```typescript
const observer = new ResizeObserver(([{ contentBoxSize }]) => {
  setSize({
    height: contentBoxSize[0].blockSize,
    width: contentBoxSize[0].inlineSize,
  });
});

if (ref.current) observer.observe(ref.current);
```

--------------------------------

### ColorService

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/README.md

Utility service for color conversion.

```APIDOC
## ColorService

### Description
A service providing color conversion utilities to generate complete IColor objects.
```

--------------------------------

### ColorService.toHex(value: string)

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Converts various string color formats (hex, CSS names, rgb functions) to hex notation.

```APIDOC
## ColorService.toHex(value: string)

### Description
Converts various string color formats to hex notation. It handles short hex, standard hex, hex with alpha, and CSS color names or functions.

### Parameters
- **value** (string) - Required - The color string to convert (e.g., "#fff", "red", "rgb(255, 0, 0)").

### Returns
- **string** - The normalized hex color string. Defaults to "#000000" on failure.
```

--------------------------------

### Track element dimensions with useBoundingClientRect hook

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/architecture.md

Tracks element size and position using window resize listeners and ResizeObserver.

```typescript
function useBoundingClientRect<T extends HTMLElement>() {
  const [size, setSize] = useState({ width: 1, height: 1 });
  
  useLayoutEffect(() => {
    // Window resize listener
    window.addEventListener("resize", onWindowResize);
    
    // Element resize observer
    const observer = new ResizeObserver(onElementResize);
    observer.observe(ref.current);
    
    return () => {
      window.removeEventListener("resize", onWindowResize);
      observer.disconnect();
    };
  }, []);
  
  return [ref, size, getPosition];
}
```

--------------------------------

### Integrate ColorPicker with Fields

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/fields-component.md

Basic implementation of the ColorPicker component with onChangeComplete handling.

```typescript
import { ColorPicker, useColor } from "react-color-palette";
import "react-color-palette/css";

export function App() {
  const [color, setColor] = useColor("#561ecb");

  const handleChangeComplete = (color) => {
    // This fires when user:
    // - Releases mouse from a picker
    // - Finishes touch interaction
    // - Blurs an input field
    console.log("Final color:", color.hex);
  };

  return (
    <ColorPicker
      color={color}
      onChange={setColor}
      onChangeComplete={handleChangeComplete}
    />
  );
}
```

--------------------------------

### Input Blur Handling

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/architecture.md

Logic executed when the user blurs the input field to finalize color changes.

```text
User blurs field
│
├─→ onInputBlur handler
│   ├─→ Parse and convert final value
│   ├─→ Invoke onChangeComplete callback
│   └─→ Set inputted=false (re-enable sync with color prop)
│
└─→ On next re-render, field value syncs with color prop
    (unless user has started editing again)
```

--------------------------------

### Custom Layout

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/INDEX.md

Manually arrange individual picker components for a custom layout.

```typescript
<div className="custom-layout">
  <Saturation height={300} color={color} onChange={setColor} />
  <Hue color={color} onChange={setColor} />
  <Alpha color={color} onChange={setColor} />
</div>
```

--------------------------------

### Use onChangeComplete callback

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

Trigger an action only after the user finishes interacting with the color picker.

```tsx
import { ColorPicker, useColor, type IColor } from "react-color-palette";
import "react-color-palette/css";

export function App() {
  const [color, setColor] = useColor("#123123");

  const onChangeComplete = (color: IColor) => localStorage.setItem("color", color.hex);

  return <ColorPicker hideInput={["rgb", "hsv"]} color={color} onChange={setColor} onChangeComplete={onChangeComplete} />
}
```

--------------------------------

### Convert RGB to HSV using ColorService

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Converts an RGB object to an HSV object using standard color space conversion.

```typescript
ColorService.rgb2hsv({ r: 255, g: 0, b: 0, a: 1 });    // { h: 0, s: 100, v: 100, a: 1 }
ColorService.rgb2hsv({ r: 128, g: 128, b: 128, a: 1 }); // { h: 0, s: 0, v: 50.2, a: 1 }
```

--------------------------------

### CSS Classes

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/INDEX.md

List of CSS classes available for styling the library components.

```css
.rcp-root              /* Root container */
.rcp-saturation        /* Saturation picker */
.rcp-saturation-cursor /* Saturation cursor */
.rcp-hue               /* Hue picker */
.rcp-hue-cursor        /* Hue cursor */
.rcp-alpha             /* Alpha picker */
.rcp-alpha-cursor      /* Alpha cursor */
.rcp-fields            /* Input fields container */
.rcp-field             /* Individual field */
.rcp-field-input       /* Input element */
.rcp-field-label       /* Field label */
.rcp-body              /* Body section */
.rcp-section           /* Control or field section */
```

--------------------------------

### isTouch Implementation

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/utilities.md

The internal implementation of the isTouch utility.

```typescript
return "touches" in event;
```

--------------------------------

### Basic ColorPicker Usage

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

Standard implementation of the ColorPicker component using the useColor hook.

```tsx
import { ColorPicker, useColor } from "react-color-palette";
import "react-color-palette/css";

export function App() {
  const [color, setColor] = useColor("#561ecb");

  return <ColorPicker color={color} onChange={setColor} />;
}
```

--------------------------------

### Manage color state with useColor hook

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/architecture.md

Synchronizes color state automatically when the initialColor prop changes.

```typescript
function useColor(initialColor: string) {
  const [color, setColor] = useState(ColorService.convert("hex", initialColor));
  
  useEffect(() => {
    // Sync when initialColor prop changes
    setColor(ColorService.convert("hex", initialColor));
  }, [initialColor]);
  
  return [color, setColor];
}
```

--------------------------------

### Support Multiple Color Formats

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/getting-started.md

The useColor hook supports various color string formats.

```typescript
// Hex color
const [color1, setColor1] = useColor("#561ecb");

// RGB format
const [color2, setColor2] = useColor("rgb(86 30 203)");

// HSL format
const [color3, setColor3] = useColor("hsl(120 100% 50%)");

// Named colors
const [color4, setColor4] = useColor("cyan");

// With transparency
const [color5, setColor5] = useColor("rgba(86, 30, 203, 0.8)");
```

--------------------------------

### formatRgb(IColorRgb)

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/utilities.md

Formats an RGB color object into a display string.

```APIDOC
## formatRgb(IColorRgb)

### Description
Converts an IColorRgb object into a string representation (e.g., "255, 0, 0").

### Parameters
- **IColorRgb** (object) - The RGB color object.

### Returns
- (string) The formatted RGB string.
```

--------------------------------

### IPosition Interface

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-bounding-client-rect.md

Defines the structure for element position relative to the viewport.

```typescript
interface IPosition {
  readonly left: number;
  readonly right: number;
  readonly top: number;
  readonly bottom: number;
}
```

--------------------------------

### Implement Type-Safe Color State

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/README.md

Demonstrates importing the ColorPicker component and useColor hook with TypeScript type definitions.

```typescript
import { ColorPicker, useColor, type IColor } from "react-color-palette";

const [color, setColor] = useColor("#ff0000");
const color: IColor = color;  // TypeScript knows the type
```

--------------------------------

### ColorService.convert()

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Converts a color value from a specified model into a complete IColor object containing hex, rgb, and hsv representations.

```APIDOC
## ColorService.convert(model, color)

### Description
Converts a color from one model to a complete IColor object with all representations.

### Parameters
- **model** (string) - Required - The color model of the input value ("hex", "rgb", or "hsv").
- **color** (any) - Required - The color value to convert, matching the specified model type.

### Returns
- **IColor** - An object containing the color in all three formats: hex, rgb, and hsv.

### Example
```typescript
const color = ColorService.convert("hex", "#ff0000");
// Returns { hex: "#ff0000", rgb: { r: 255, g: 0, b: 0, a: 1 }, hsv: { h: 0, s: 100, v: 100, a: 1 } }
```
```

--------------------------------

### Handle Interaction Completion

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/getting-started.md

Use onChangeComplete to trigger actions only when the user finishes interacting with the picker.

```typescript
const [color, setColor] = useColor("#123123");

const handleChangeComplete = (finalColor: IColor) => {
  localStorage.setItem("color", finalColor.hex);
};

return (
  <ColorPicker
    color={color}
    onChange={setColor}
    onChangeComplete={handleChangeComplete}
  />
);
```

--------------------------------

### Convert HSV to RGB using ColorService

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Converts an HSV object to an RGB object using standard color space conversion.

```typescript
ColorService.hsv2rgb({ h: 0, s: 100, v: 100, a: 1 });    // { r: 255, g: 0, b: 0, a: 1 }
ColorService.hsv2rgb({ h: 120, s: 100, v: 100, a: 1 });  // { r: 0, g: 255, b: 0, a: 1 }
```

--------------------------------

### Define convert() Method Signature

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

The type signature for the primary conversion method.

```typescript
convert<M extends keyof IColor, C extends IColor[M]>(model: M, color: C): IColor
```

--------------------------------

### Hook Signature

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-color.md

The TypeScript signature for the useColor hook.

```typescript
function useColor(
  initialColor: string
): [IColor, React.Dispatch<React.SetStateAction<IColor>>]
```

--------------------------------

### Distinguish Complete vs Intermediate Changes

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/INDEX.md

Use onChangeComplete to trigger actions only when the user finishes interacting with the picker.

```typescript
<ColorPicker
  color={color}
  onChange={setColor}
  onChangeComplete={(finalColor) => {
    localStorage.setItem("color", finalColor.hex);
  }}
/>
```

--------------------------------

### ColorService.rgb2hsv

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Converts an RGB object to an HSV object.

```APIDOC
## ColorService.rgb2hsv(rgb: IColor["rgb"]): IColor["hsv"]

### Description
Converts an RGB color object to HSV using standard color space conversion algorithms.

### Parameters
- **rgb** (object) - Required - The RGB color object containing r, g, b, and a values.

### Returns
- **IColor["hsv"]** - An object containing h, s, v, and a values.
```

--------------------------------

### ISize Interface

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-bounding-client-rect.md

Defines the structure for element dimensions.

```typescript
interface ISize {
  readonly width: number;
  readonly height: number;
}
```

--------------------------------

### Interactive Component Signature

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/interactive-component.md

The TypeScript functional component signature for the Interactive wrapper.

```typescript
const Interactive: React.FC<IInteractiveProps>
```

--------------------------------

### Saturation Component Signature

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/saturation.md

The TypeScript functional component signature for the Saturation picker.

```typescript
const Saturation: React.FC<ISaturationProps>
```

--------------------------------

### Handle interactive component movement

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/architecture.md

Calculates clamped coordinates based on mouse events and element position.

```typescript
const move = useCallback((event, final = false) => {
  const { left, top } = getPosition();
  const x = clamp(event.clientX - left, 0, width);
  const y = clamp(event.clientY - top, 0, height);
  onCoordinateChange(final, x, y);
}, [width, height, getPosition, onCoordinateChange]);
```

--------------------------------

### ColorService.hsv2rgb

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Converts an HSV object to an RGB object.

```APIDOC
## ColorService.hsv2rgb(hsv: IColor["hsv"]): IColor["rgb"]

### Description
Converts an HSV color object to RGB using standard color space conversion algorithms.

### Parameters
- **hsv** (object) - Required - The HSV color object containing h, s, v, and a values.

### Returns
- **IColor["rgb"]** - An object containing r, g, b, and a values.
```

--------------------------------

### Picker Interaction Data Flow

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/architecture.md

Sequence of events triggered by mouse or touch interactions within the picker components.

```text
User interaction (mouse/touch)
│
├─→ Interactive component
│   ├─→ Detect mouse vs touch
│   ├─→ Calculate element-relative coordinates
│   └─→ Invoke onCoordinateChange callback
│
├─→ Saturation.updateColor / Hue.updateColor / Alpha.updateColor
│   ├─→ Map coordinates to HSV delta (s, v, h, or a)
│   ├─→ Convert merged HSV to complete IColor via ColorService.convert("hsv", ...)
│   └─→ Invoke onChange callback with new IColor
│
└─→ Parent component (typically via useColor setter)
    └─→ Update state → re-render
        ├─→ ColorPicker re-renders
        ├─→ Fields component updates display values (if not user-editing)
        └─→ All pickers receive new color prop → re-render cursors
```

--------------------------------

### Convert color in Saturation component

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Updates color state based on coordinate-based saturation and value calculations.

```typescript
// In Saturation component
const nextColor = ColorService.convert("hsv", {
  ...color.hsv,
  s: (x / width) * 100,
  v: 100 - (y / height) * 100,
});
onChange(nextColor);
```

--------------------------------

### Individual Picker Props

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/INDEX.md

The IPickerProps interface defines the properties for individual color picker components like Saturation, Hue, and Alpha.

```APIDOC
## IPickerProps

### Description
Base properties for individual picker components.

### Properties
- **color** (IColor) - Required - The current color state.
- **onChange** ((color: IColor) => void) - Required - Callback fired on any color change.
- **disabled** (boolean) - Optional - Disable interaction (default false).
- **onChangeComplete** ((color: IColor) => void) - Optional - Callback fired on interaction end.

### Component Specific Props
- **Saturation**: height (number) - Required
```

--------------------------------

### useBoundingClientRect Hook Signature

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-bounding-client-rect.md

The hook returns a tuple containing a ref, size object, and a position getter function.

```typescript
function useBoundingClientRect<T extends HTMLElement>(): [
  React.RefObject<T>,
  ISize,
  () => IPosition
]
```

--------------------------------

### Convert colors to hex with toHex

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Converts CSS color strings, names, or shorthand hex values into standard 6-digit hex notation.

```typescript
ColorService.toHex("#fff");        // "#ffffff"
ColorService.toHex("red");         // "#ff0000"
ColorService.toHex("rgb(255, 0, 0)"); // "#ff0000"
ColorService.toHex("#ff0000");     // "#ff0000"
```

--------------------------------

### Hue Component Signature

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/hue.md

The TypeScript signature for the Hue component.

```typescript
const Hue: React.FC<IHueProps>
```

--------------------------------

### Convert coordinates to color model

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/interactive-component.md

Implement the updateColor callback to map X/Y coordinates to specific color model values.

```typescript
// Saturation: coordinates to saturation and value
const updateColor = (final, x, y) => {
  const nextColor = ColorService.convert("hsv", {
    ...color.hsv,
    s: (x / width) * 100,
    v: 100 - (y / height) * 100,
  });
  onChange(nextColor);
  if (final) onChangeComplete?.(nextColor);
};
```

--------------------------------

### ColorService.rgb2hex

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Converts an RGB object to a hex string.

```APIDOC
## ColorService.rgb2hex(rgb: IColor["rgb"]): IColor["hex"]

### Description
Converts an RGB color object to a hex string. It rounds values to integers and includes the alpha channel if it is not fully opaque.

### Parameters
- **rgb** (object) - Required - The RGB color object containing r, g, b, and a values.

### Returns
- **IColor["hex"]** - A hex string representation of the color.
```

--------------------------------

### Format HSV color objects

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/utilities.md

Converts an HSV object into a string with degree and percentage symbols. Alpha is appended if not fully opaque.

```typescript
function formatHsv(hsv: IColor["hsv"]): string
```

```typescript
formatHsv({ h: 0, s: 100, v: 100, a: 1 });    // "0°, 100%, 100%"
formatHsv({ h: 120, s: 50, v: 75, a: 1 });    // "120°, 50%, 75%"
formatHsv({ h: 240, s: 100, v: 100, a: 0.5 }); // "240°, 100%, 100%, 0.5"
```

```typescript
const [fields, setFields] = useState({
  hsv: {
    value: formatHsv(color.hsv),
    inputted: false,
  },
  // ...
});
```

--------------------------------

### float(value, places)

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/utilities.md

Rounds a number to a specific number of decimal places.

```APIDOC
## float(value, places)

### Description
Utility to round a numeric value to a defined number of decimal places.

### Parameters
- **value** (number) - The number to round.
- **places** (number) - The number of decimal places to keep.

### Returns
- (number) The rounded number.
```

--------------------------------

### formatHsv(IColorHsv)

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/utilities.md

Formats an HSV color object into a display string.

```APIDOC
## formatHsv(IColorHsv)

### Description
Converts an IColorHsv object into a string representation (e.g., "0°, 100%, 100%").

### Parameters
- **IColorHsv** (object) - The HSV color object.

### Returns
- (string) The formatted HSV string.
```

--------------------------------

### Define ColorService Interface

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

The static class definition for ColorService, outlining available conversion methods.

```typescript
class ColorServiceStatic {
  convert<M extends keyof IColor, C extends IColor[M]>(model: M, color: C): IColor
  toHex(value: string): IColor["hex"]
  toRgb(value: string): IColor["rgb"]
  toHsv(value: string): IColor["hsv"]
  hex2rgb(hex: IColor["hex"]): IColor["rgb"]
  rgb2hsv(rgb: IColor["rgb"]): IColor["hsv"]
  hsv2rgb(hsv: IColor["hsv"]): IColor["rgb"]
  rgb2hex(rgb: IColor["rgb"]): IColor["hex"]
}

export const ColorService: ColorServiceStatic
```

--------------------------------

### Normalize mouse and touch events in Interactive component

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/architecture.md

Handles input events by distinguishing between touch and mouse interactions to ensure consistent behavior across devices.

```typescript
if (isTouch(event)) {
  // Use event.touches[0] or event.changedTouches[0]
  document.addEventListener("touchmove", onMove);
  document.addEventListener("touchend", onEnd);
} else {
  // Use event directly
  document.addEventListener("mousemove", onMove);
  document.addEventListener("mouseup", onEnd);
}
```

--------------------------------

### Basic usage of useBoundingClientRect

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-bounding-client-rect.md

Attach the returned ref to a DOM element to access its dimensions and the getPosition function.

```typescript
// In a component
const [ref, { width, height }, getPosition] = useBoundingClientRect<HTMLDivElement>();

// Attach ref to a DOM element
<div ref={ref}>
  {/* content */}
</div>

// Read current size
console.log(`Element is ${width}px wide and ${height}px tall`);

// Get position at any time
const { left, top } = getPosition();
```

--------------------------------

### Restrict input formats

Source: https://github.com/wondermarin/react-color-palette/blob/main/README.md

Hide specific color input fields by passing the hideInput prop to the ColorPicker.

```tsx
import { ColorPicker, useColor } from "react-color-palette";
import "react-color-palette/css";

export function App() {
  const [color, setColor] = useColor("#123123");

  return <ColorPicker hideInput={["rgb", "hsv"]} color={color} onChange={setColor} />
}
```

--------------------------------

### ColorPicker Component Signature

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-picker.md

The TypeScript signature for the ColorPicker component.

```typescript
const ColorPicker: React.FC<IColorPickerProps>
```

--------------------------------

### Define IPickerProps interface

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/INDEX.md

Base properties for individual picker components like Saturation, Hue, and Alpha.

```typescript
interface IPickerProps {
  color: IColor;                           // Required
  onChange: (color: IColor) => void;       // Required
  disabled?: boolean;                      // Optional (default false)
  onChangeComplete?: (color: IColor) => void; // Optional
}
```

--------------------------------

### useBoundingClientRect<T>()

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/use-bounding-client-rect.md

A hook that returns a ref to attach to an element, the current dimensions of that element, and a function to retrieve the current bounding client rectangle position.

```APIDOC
## useBoundingClientRect<T>()

### Description
Returns a tuple containing a ref object, the current dimensions of the element, and a function to get the current position. It handles window resize events to update dimensions automatically.

### Returns
- **ref** (RefObject<T>) - The ref to be attached to the target element.
- **dimensions** (Object) - The current width and height of the element.
  - **width** (number)
  - **height** (number)
- **getPosition** (Function) - A function that returns the current DOMRect (left, top) of the element, including sub-pixel precision.

### Usage Example
```typescript
const [ref, { width, height }, getPosition] = useBoundingClientRect<HTMLDivElement>();

const handleInteraction = (event) => {
  const { left, top } = getPosition();
  const x = event.clientX - left;
  const y = event.clientY - top;
};
```
```

--------------------------------

### Programmatic Color Updates

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/getting-started.md

Update the color state externally using ColorService.

```typescript
import { ColorService, useColor } from "react-color-palette";

export function App() {
  const [color, setColor] = useColor("#ff0000");

  const selectPrimaryColor = () => {
    setColor(ColorService.convert("hex", "#0066ff"));
  };

  const selectAccentColor = () => {
    setColor(ColorService.convert("hex", "#ff6600"));
  };

  return (
    <div>
      <ColorPicker color={color} onChange={setColor} />
      <button onClick={selectPrimaryColor}>Primary</button>
      <button onClick={selectAccentColor}>Accent</button>
      <p>Selected: {color.hex}</p>
    </div>
  );
}
```

--------------------------------

### Define IColor model structure

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/README.md

The IColor interface represents the color state used throughout the library, containing hex, rgb, and hsv color space data.

```typescript
IColor {
  hex: string         // "#RRGGBB" or "#RRGGBBAA"
  rgb: {
    r: 0-255          // Red channel
    g: 0-255          // Green channel
    b: 0-255          // Blue channel
    a: 0-1            // Alpha (normalized)
  }
  hsv: {
    h: 0-360          // Hue angle
    s: 0-100          // Saturation %
    v: 0-100          // Value/Brightness %
    a: 0-1            // Alpha (normalized)
  }
}
```

--------------------------------

### Define IColorPickerProps interface

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/INDEX.md

Configuration properties for the main ColorPicker component.

```typescript
interface IColorPickerProps {
  color: IColor;                           // Required: Current color
  onChange: (color: IColor) => void;       // Required: Fired on any change
  height?: number;                         // Optional: Saturation height (default 200)
  hideAlpha?: boolean;                     // Optional: Hide alpha picker (default false)
  hideInput?: (keyof IColor)[] | boolean;  // Optional: Hide input fields (default false)
  disabled?: boolean;                      // Optional: Disable interaction (default false)
  onChangeComplete?: (color: IColor) => void; // Optional: Fired on interaction end
}
```

--------------------------------

### Configure hideInput prop using keyof IColor

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/types.md

Defines the hideInput type as an array of IColor keys or a boolean to toggle field visibility.

```typescript
// This type means: array of field names that exist in IColor
type hideInput = (keyof IColor)[] | boolean;

// Valid values for the array:
["hex"]              // Hide hex field only
["rgb", "hsv"]       // Hide RGB and HSV fields
["hex", "rgb", "hsv"] // Hide all fields
```

--------------------------------

### Parse RGB strings with toRgb

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/color-service.md

Extracts numeric values from RGB strings and returns an object with clamped R, G, B, and A components.

```typescript
ColorService.toRgb("rgb(255, 128, 64)");        // { r: 255, g: 128, b: 64, a: 1 }
ColorService.toRgb("rgb(255 128 64 / 0.5)");   // { r: 255, g: 128, b: 64, a: 0.5 }
```

--------------------------------

### isTouch in Interactive Components

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/utilities.md

Using isTouch to dynamically attach appropriate event listeners.

```typescript
const onStart = (event: TInteractionEvent) => {
  // ... setup logic ...
  document.addEventListener(
    isTouch(event) ? "touchmove" : "mousemove",
    onMove,
    false
  );
  document.addEventListener(
    isTouch(event) ? "touchend" : "mouseup",
    onEnd,
    false
  );
};
```

--------------------------------

### Define IColor Interface

Source: https://github.com/wondermarin/react-color-palette/blob/main/_autodocs/types.md

The IColor interface provides a unified structure for accessing color data in multiple formats.

```typescript
interface IColor {
  readonly hex: string;
  readonly rgb: IColorRgb;
  readonly hsv: IColorHsv;
}
```
Tokens:
Raw