The color picker primarily takes a CSS HEX string representing any color. Users can adjust the color by changing the saturation, value, or hue of the HEX value.

Inside the component, colors are represented in the HSV color space, as HEX color codes are lossy when it comes to, specifically, hue.

At this time, users can't directly input hue, saturation, value, or alpha values.

<ColorPicker color='#005719' onColorChange={(color) => console.log(color)} />

By default, the color cannot be null and users can't clear the color value. When it makes sense, the color picker can allow the color to be cleared (with an x button in the HEX input) and set to null. To allow null and allow the color to be cleared in the HEX input, set isClearable to true.

import { ColorPicker } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
  const [color, setColor] = useState('#005719');

  return (
    <ColorPicker
      color={color}
      onColorChange={(color) => {
        console.log(color);
        setColor(color);
      }}
      isClearable={true}
    />
  )
}

Disabling changes

When the color picker shouldn't accept any changes by the user, set isDisabled to true. Users will still be able to open the color picker, but won't be able to change the hue, saturation/value, or HEX values.

<ColorPicker
  color='#005719'
  onColorChange={(color) => console.log(color)}
  isDisabled={true}
/>

API

`PlumaColorPicker` `extends Box`

`additionalMiddleware` `{ name: string; options?: any; fn: (state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => Promisable<MiddlewareReturn>; }[] | undefined`

Additional middleware to apply to Floating UI, for example custom middleware for more control. These will be applied after the default middleware.

`animationTransitionDuration` `number | undefined`

Default:125

The duration (in ms) for the popover animation.

`color` `string` (required)

The currently selected color. This component does not manage this state for you and you must manage the selected color yourself.

It should be a CSS HEX color value without an alpha channel.

`defaultIsOpen` `boolean | undefined`

Whether the popover should be open initially

`floatingPluginOptions` { click?: { enabled?: boolean | undefined; event?: "click" | "mousedown" | undefined; toggle?: boolean | undefined; ignoreMouse?: boolean | undefined; keyboardHandlers?: boolean | undefined; } | undefined; hover?: { enabled?: boolean | undefined; mouseOnly?: boolean | undefined; delay?: number | Partial<{ open: number; close: number; }> | undefined; restMs?: number | undefined; move?: boolean | undefined; handleClose?: any; } | undefined; focus?: { enabled?: boolean | undefined; visibleOnly?: boolean | undefined; } | undefined; dismiss?: { enabled?: boolean | undefined; escapeKey?: boolean | undefined; referencePress?: boolean | undefined; referencePressEvent?: "click" | "mousedown" | "pointerdown" | undefined; outsidePress?: boolean | ((event: MouseEvent) => boolean) | undefined; outsidePressEvent?: "click" | "mousedown" | "pointerdown" | undefined; ancestorScroll?: boolean | undefined; bubbles?: boolean | { escapeKey?: boolean | undefined; outsidePress?: boolean | undefined; } | undefined; capture?: boolean | { escapeKey?: boolean | undefined; outsidePress?: boolean | undefined; } | undefined; } | undefined; role?: { enabled?: boolean | undefined; role?: "grid" | "listbox" | "menu" | "tooltip" | "dialog" | "label" | "select" | "tree" | "alertdialog" | "combobox" | undefined; } | undefined; } | undefined

Additional options to pass to Floating UI's plugins/hooks.

`focusOrder` `("content" | "reference" | "floating")[] | undefined`

Default:['content']

The order in which focus should be moved when navigating through the popover. See Floating UI for more details.

`initialFocus` `number | HTMLElement | undefined`

Default:0

Which element to initially focus when the popover is opened. Can be a number (a tabbable index as specified by focusOrder) or an HTMLElement. See Floating UI for more details.

`isClearable` `boolean | undefined`

Default:false

Whether to allow the user to clear the color or not. Defaults to false.

`isDisabled` `boolean | undefined`

Default:false

Whether the color picker should be disabled. Defaults to false.

`isDraggable` `boolean | undefined`

Default:false

Whether the popover should be draggable.

`isFocusManagerDisabled` `boolean | undefined`

Default:false

Whether the focus manager (for the opened popover) should be disabled entirely. See Floating UI for more details.

`isOpen` `boolean | undefined`

Whether the popover should be open. Only use this along with onOpenChange if you want to control the state of the popover

`listNavigationOptions` `{ activeIndex?: number | null | undefined; onNavigate?: ((activeIndex: number | null) => void) | undefined; loop?: boolean | undefined; virtual?: boolean | undefined; allowEscape?: boolean | undefined; focusItemOnHover?: boolean | undefined; focusItemOnOpen?: boolean | undefined; } | undefined`

Additional options to pass to Floating UI's list navigation plugin.

`middlewareOptions` { arrow?: Partial<{ padding?: Padding | undefined; element: Element; }> | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => Partial<{ padding?: Padding | undefined; element: Element; }>) | undefined; offset?: Partial<{ mainAxis: number; crossAxis: number; alignmentAxis: number | null; }> | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => Partial<{ mainAxis: number; crossAxis: number; alignmentAxis: number | null; }>) | undefined; flip?: { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; fallbackPlacements?: Placement[] | undefined; fallbackStrategy?: "initialPlacement" | "bestFit" | undefined; fallbackAxisSideDirection?: "none" | "end" | "start" | undefined; flipAlignment?: boolean | undefined; boundary?: Boundary | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; fallbackPlacements?: Placement[] | undefined; fallbackStrategy?: "initialPlacement" | "bestFit" | undefined; fallbackAxisSideDirection?: "none" | "end" | "start" | undefined; flipAlignment?: boolean | undefined; boundary?: Boundary | undefined; }) | undefined; shift?: { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; limiter?: { fn: (state: MiddlewareState) => Coords; options?: any; } | undefined; boundary?: Boundary | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; limiter?: { fn: (state: MiddlewareState) => Coords; options?: any; } | undefined; boundary?: Boundary | undefined; }) | undefined; hide?: { padding?: Padding | undefined; strategy?: "referenceHidden" | "escaped" | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; strategy?: "referenceHidden" | "escaped" | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; }) | undefined; size?: { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; apply?: ((args: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; } & { availableWidth: number; availableHeight: number; }) => Promisable<void>) | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; apply?: ((args: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; } & { availableWidth: number; availableHeight: number; }) => Promisable<void>) | undefined; }) | undefined; } | undefined

Additional options to pass into Floating UI middleware

`onColorChange` `(hex: string) => unknown` (required)

The function called when the user changes the color. Use this to update the current color state. If isClearable is set to true, the color passed into the function can be null

`onOpenChange` `((isOpen: boolean, event?: Event | undefined, reason?: "focus" | "hover" | "outside-press" | "escape-key" | "ancestor-scroll" | "reference-press" | "click" | "list-navigation" | "safe-polygon" | undefined) => void) | undefined`

Called when the open state of the popover is changing

`placement` `Placement | undefined`

Where the popover should be placed in relation to the trigger

`shouldCloseOnFocusOut` `boolean | undefined`

Default:true

Whether focusout event listeners are attached to the trigger and popover, to close the popover when focus moves outside of it. See Floating UI for more details.

`shouldNavigateList` `boolean | undefined`

Default:false

Whether the popover should navigate through a list of items when the arrow keys are pressed. See Floating UI for more details.

`shouldRenderFocusGuards` `boolean | undefined`

Default:true

Whether the focus guards are rendered by the focus manager. See Floating UI for more details.

`shouldRestrictSize` `boolean | { width?: boolean | undefined; height?: boolean | undefined; } | undefined`

Default:true

Whether the popover content's max width and/or max height should be restricted using the Floating UI size middleware.

By default, this is enabled, to prevent popovers from growing larger than the available viewport size.

ColorPicker

Usage

Clearing the color

Disabling changes

API

`PlumaColorPicker` `extends Box`

`animationTransitionDuration` `number | undefined`

`color` `string` (required)

`defaultIsOpen` `boolean | undefined`

`focusOrder` `("content" | "reference" | "floating")[] | undefined`

`initialFocus` `number | HTMLElement | undefined`

`isClearable` `boolean | undefined`

`isDisabled` `boolean | undefined`

`isDraggable` `boolean | undefined`

`isFocusManagerDisabled` `boolean | undefined`

`isOpen` `boolean | undefined`

`onColorChange` `(hex: string) => unknown` (required)

`onOpenChange` `((isOpen: boolean, event?: Event | undefined, reason?: "focus" | "hover" | "outside-press" | "escape-key" | "ancestor-scroll" | "reference-press" | "click" | "list-navigation" | "safe-polygon" | undefined) => void) | undefined`

`placement` `Placement | undefined`

`shouldCloseOnFocusOut` `boolean | undefined`

`shouldNavigateList` `boolean | undefined`

`shouldRenderFocusGuards` `boolean | undefined`

`shouldRestrictSize` `boolean | { width?: boolean | undefined; height?: boolean | undefined; } | undefined`

`shouldReturnFocus` `boolean | undefined`

`shouldShowVisuallyHiddenDismiss` `boolean | undefined`

`shouldTrapFocus` `boolean | undefined`

`shouldTriggerOnClick` `boolean | undefined`

`shouldTriggerOnFocus` `boolean | undefined`

`shouldTriggerOnHover` `boolean | undefined`

`strategy` `Strategy | undefined`

`unsafe_popoverClassName` `string | undefined`

`unsafe_popoverContentClassName` `string | undefined`

`unsafe_popoverStyle` `Record<string, unknown> | undefined`

`unsafe_registerNodeId` `((id: string) => void) | undefined`

`withTypeahead` `boolean | undefined`

On this page

ColorPicker

Usage

Clearing the color

Disabling changes

API

PlumaColorPicker extends Box

animationTransitionDuration number | undefined

color string (required)

defaultIsOpen boolean | undefined

focusOrder ("content" | "reference" | "floating")[] | undefined

initialFocus number | HTMLElement | undefined

isClearable boolean | undefined

isDisabled boolean | undefined

isDraggable boolean | undefined

isFocusManagerDisabled boolean | undefined

isOpen boolean | undefined

onColorChange (hex: string) => unknown (required)

onOpenChange ((isOpen: boolean, event?: Event | undefined, reason?: "focus" | "hover" | "outside-press" | "escape-key" | "ancestor-scroll" | "reference-press" | "click" | "list-navigation" | "safe-polygon" | undefined) => void) | undefined

placement Placement | undefined

shouldCloseOnFocusOut boolean | undefined

shouldNavigateList boolean | undefined

shouldRenderFocusGuards boolean | undefined

shouldRestrictSize boolean | { width?: boolean | undefined; height?: boolean | undefined; } | undefined

shouldReturnFocus boolean | undefined

shouldShowVisuallyHiddenDismiss boolean | undefined

shouldTrapFocus boolean | undefined

shouldTriggerOnClick boolean | undefined

shouldTriggerOnFocus boolean | undefined

shouldTriggerOnHover boolean | undefined

strategy Strategy | undefined

unsafe_popoverClassName string | undefined

unsafe_popoverContentClassName string | undefined

unsafe_popoverStyle Record<string, unknown> | undefined

unsafe_registerNodeId ((id: string) => void) | undefined

withTypeahead boolean | undefined

On this page

`PlumaColorPicker` `extends Box`

`animationTransitionDuration` `number | undefined`

`color` `string` (required)

`defaultIsOpen` `boolean | undefined`

`focusOrder` `("content" | "reference" | "floating")[] | undefined`

`initialFocus` `number | HTMLElement | undefined`

`isClearable` `boolean | undefined`

`isDisabled` `boolean | undefined`

`isDraggable` `boolean | undefined`

`isFocusManagerDisabled` `boolean | undefined`

`isOpen` `boolean | undefined`

`onColorChange` `(hex: string) => unknown` (required)

`onOpenChange` `((isOpen: boolean, event?: Event | undefined, reason?: "focus" | "hover" | "outside-press" | "escape-key" | "ancestor-scroll" | "reference-press" | "click" | "list-navigation" | "safe-polygon" | undefined) => void) | undefined`

`placement` `Placement | undefined`

`shouldCloseOnFocusOut` `boolean | undefined`

`shouldNavigateList` `boolean | undefined`

`shouldRenderFocusGuards` `boolean | undefined`

`shouldRestrictSize` `boolean | { width?: boolean | undefined; height?: boolean | undefined; } | undefined`

`shouldReturnFocus` `boolean | undefined`

`shouldShowVisuallyHiddenDismiss` `boolean | undefined`

`shouldTrapFocus` `boolean | undefined`

`shouldTriggerOnClick` `boolean | undefined`

`shouldTriggerOnFocus` `boolean | undefined`

`shouldTriggerOnHover` `boolean | undefined`

`strategy` `Strategy | undefined`

`unsafe_popoverClassName` `string | undefined`

`unsafe_popoverContentClassName` `string | undefined`

`unsafe_popoverStyle` `Record<string, unknown> | undefined`

`unsafe_registerNodeId` `((id: string) => void) | undefined`

`withTypeahead` `boolean | undefined`