@choiceform/colors

A powerful color management and picker component library for design systems.

Features

• 🎨 Rich color picker components
• 🔍 Support for multiple color formats (HEX, RGB, HSL, HSB)
• 🌈 Gradient, solid color, pattern, and image support
• 🧩 Highly customizable extension capabilities
• 📚 Easy-to-integrate API
• 🔌 Dynamic tabs extension system
• 📋 Color contrast checking functionality

Installation

npm install @choiceform/colors

or

yarn add @choiceform/colors

Basic Usage

Simple Color Picker

import { useState } from "react"
import { ColorPickerPopover, ColorSolidPaint } from "@choiceform/colors"
import type { RGB } from "@choiceform/colors"

function ColorPickerExample() {
  const [color, setColor] = useState<RGB>({ r: 66, g: 133, b: 244 })
  const [alpha, setAlpha] = useState<number>(1)
  const [open, setOpen] = useState<boolean>(false)

  return (
    <ColorPickerPopover
      open={open}
      onOpenChange={setOpen}
      solidPaint={
        <ColorSolidPaint
          color={color}
          alpha={alpha}
          onColorChange={setColor}
          onAlphaChange={setAlpha}
        />
      }
    >
      <div
        className="h-12 w-12 cursor-pointer rounded"
        style={{
          backgroundColor: `rgba(${color.r}, ${color.g}, ${color.b}, ${alpha})`,
        }}
        onClick={() => setOpen(true)}
      />
    </ColorPickerPopover>
  )
}

Gradient Picker

import { useState } from "react"
import { ColorPickerPopover, ColorSolidPaint, ColorGradientsPaint } from "@choiceform/colors"
import type { RGB, GradientPaint } from "@choiceform/colors"

function GradientPickerExample() {
  const [color, setColor] = useState<RGB>({ r: 66, g: 133, b: 244 })
  const [gradient, setGradient] = useState<GradientPaint>({
    type: "GRADIENT_LINEAR",
    gradientStops: [
      { id: "1", position: 0, color: { r: 255, g: 0, b: 0 }, alpha: 1 },
      { id: "2", position: 1, color: { r: 0, g: 0, b: 255 }, alpha: 1 },
    ],
    gradientTransform: [
      [1, 0, 0],
      [0, 1, 0],
    ],
  })

  // ...
}

Advanced Features

Dynamic Tabs System

The Colors library provides a powerful dynamic tabs system that allows you to extend the color picker's functionality:

import { ColorPickerPopover, ColorSolidPaint } from "@choiceform/colors"

function CustomTabsExample() {
  // ...

  // Custom tab content
  const customPaletteContent = (
    <div className="p-4">
      <h3>Custom Palette</h3>
      {/* Custom content */}
    </div>
  )

  // Define additional tabs
  const additionalTabs = [
    {
      value: "CUSTOM_PALETTE",
      label: "Palette",
      content: customPaletteContent,
    },
  ]

  return (
    <ColorPickerPopover
      additionalTabs={additionalTabs}
      solidPaint={<ColorSolidPaint /* ... */ />}
      // ...other properties
    />
  )
}

Features Configuration

You can control the functionality of the color picker through the features property:

<ColorPickerPopover
  features={{
    containerWidth: 240,
    spaceDropdown: true,
    alpha: true,
    hex: true,
    rgb: true,
    hsl: true,
    hsb: true,
    nativePicker: true,
    presets: true,
    pickerType: true,
    custom: true,
    paintsType: true,
    solid: true,
    gradient: true,
    pattern: true,
    image: true,
    checkColorContrast: true,
  }}
  // ...other properties
/>

Color Contrast Checking

Support for checking color accessibility contrast:

<ColorPickerPopover
  checkColorContrast={{
    backgroundColor: { r: 255, g: 255, b: 255 },
    foregroundColor: color,
    foregroundAlpha: alpha,
    level: "AA",
    category: "normal-text",
    // ...other configurations
  }}
  // ...other properties
/>

API Reference

ColorPickerPopover

The main color picker component.

| Property | Type | Default | Description | | -------------------- | ------------------------------- | ---------- | ---------------------------------- | | open | boolean | - | Control the popup state | | onOpenChange | (open: boolean) => void | - | Popup state change callback | | pickerType | string | "CUSTOM" | Picker type | | onPickerTypeChange | (type: string) => void | - | Picker type change callback | | paintsType | Paint["type"] | "SOLID" | Paint type | | onPaintsTypeChange | (type: Paint["type"]) => void | - | Paint type change callback | | solidPaint | ReactNode | - | Solid paint component | | gradientPaint | ReactNode | - | Gradient paint component | | additionalTabs | TabItem[] | [] | Additional tabs configuration | | features | PickerFeatures | - | Feature configuration | | checkColorContrast | ColorContrast | - | Color contrast check configuration | | ...others | PopoverProps | - | Properties inherited from Popover |

Related Types

// Tab item
interface TabItem {
  value: string
  label: string
  content: ReactNode
}

// Features configuration
interface PickerFeatures {
  containerWidth?: number
  spaceDropdown?: boolean
  alpha?: boolean
  hex?: boolean
  rgb?: boolean
  hsl?: boolean
  hsb?: boolean
  nativePicker?: boolean
  presets?: boolean
  variables?: boolean
  styles?: boolean
  pickerType?: boolean
  custom?: boolean
  paintsType?: boolean
  solid?: boolean
  gradient?: boolean
  pattern?: boolean
  image?: boolean
  checkColorContrast?: boolean
}

Contributing

Contributions to @choiceform/colors through PRs and Issues are welcome. Please ensure you follow the project's code style and testing standards before submitting.

License

MIT