@choiceform/colors NPM

@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

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.