ColorPicker

Choose colors for content and branding.

Choose a color

Click the swatch, color value or any empty area of the control to open the picker.

Current color：#20834a

basic.tsx

import { ColorPicker, Space, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function ColorPickerBasic() {
  const [color, setColor] = useState('#20834a');
  return (
    <Space direction="vertical" align="start">
      <ColorPicker value={color} onChange={setColor} showText aria-label="Brand color" />
      <Text tone="muted">Current color：{color}</Text>
    </Space>
  );
}

Formats and transparency

HEX

RGB · Transparent

HSL · Opaque

formats.tsx

import { ColorPicker, Flex, Text } from '@ifhover/leaf-ui';

export function ColorPickerFormats() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>HEX</Text>
        <ColorPicker defaultValue="#1677ff" showText />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>RGB · Transparent</Text>
        <ColorPicker defaultValue="rgba(118, 84, 198, 0.6)" defaultFormat="rgb" showText />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>HSL · Opaque</Text>
        <ColorPicker defaultValue="hsl(35, 91%, 55%)" defaultFormat="hsl" disableAlpha showText />
      </Flex>
    </Flex>
  );
}

Presets and states

Custom presets · Clearable

Disabled

presets.tsx

import type { ColorPreset } from '@ifhover/leaf-ui';

import { ColorPicker, Flex, Text } from '@ifhover/leaf-ui';

const presets: readonly ColorPreset[] = [
  { label: 'Brand colors', colors: ['#20834a', '#1677ff', '#7654c6', '#f49b23'] },
  { label: 'Neutral colors', colors: ['#203329', '#6c7c71', '#dce5de', '#ffffff'] },
];

export function ColorPickerPresets() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>Custom presets · Clearable</Text>
        <ColorPicker presets={presets} allowClear showText />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Disabled</Text>
        <ColorPicker disabled defaultValue="#1677ff" showText />
      </Flex>
    </Flex>
  );
}

Gradients

Solid color

Gradient: select, add or remove stops

capabilities.tsx

import { ColorPicker, Flex, Space, Text } from '@ifhover/leaf-ui';

export function Capabilities() {
  return (
    <Space>
      <Flex direction="column" gap="sm" align="center">
        <Text>{'Solid color'}</Text>
        <ColorPicker showText />
      </Flex>
      <Flex direction="column" gap="sm" align="center">
        <Text>
          {'Gradient: select, add or remove stops'}
        </Text>
        <ColorPicker
          mode="gradient"
          showText
          defaultValue="linear-gradient(90deg, #20834a 0%, #83cf9e 100%)"
        />
      </Flex>
    </Space>
  );
}

ColorPicker API

Property	Type	Default	Description
`popupPlacement`	`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'`	—	Placement relative to the trigger.
`popupClassName`	`string`	—	Custom class for the popup.
`popupStyle`	`CSSProperties`	—	Custom popup styles.
`popupRender`	`(content: ReactNode) => ReactNode`	—	Wrap or extend popup content; retain the supplied content to preserve interaction.
`getPopupContainer`	`() => Element \| DocumentFragment`	—	Return a popup container, including a ShadowRoot.
`value`	`string`	`'#20834a'`	Controlled / initial color. Accepts HEX, RGB, HSL or CSS named colors
`defaultValue`	`string`	`'#20834a'`	Controlled / initial color. Accepts HEX, RGB, HSL or CSS named colors
`onChange`	`(color: string) => void`	—	Live change / end of an adjustment; clearing returns an empty string
`onChangeComplete`	`(color: string) => void`	—	Live change / end of an adjustment; clearing returns an empty string
`format`	`'hex' \| 'rgb' \| 'hsl'`	`'hex'`	Color text format, applied to each stop in gradient mode.
`defaultFormat`	`'hex' \| 'rgb' \| 'hsl'`	`'hex'`	Initial color text format.
`onFormatChange`	`(format: 'hex' \| 'rgb' \| 'hsl') => void`	—	Called when the color text format changes.
`disableAlpha`	`boolean`	`false`	Hide opacity and output opaque colors
`showText`	`boolean \| ((color: string) => ReactNode)`	`false`	Show color text or custom content
`allowClear`	`boolean`	`false`	Allow clearing
`presets`	`readonly ColorPreset[]`	Built-in colors	Groups of preset colors.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Trigger size
`status`	`'error' \| 'warning'`	—	Validation status
`required`	`boolean`	`false`	Require a non-empty value; compound controls validate once.
`readOnly`	`boolean`	—	Lock the value against typing, selection, clearing and removal.
`popupWidth`	`number \| string`	`280`	Panel width
`onOpenChange`	`(open: boolean) => void`	—	Open state changes
`gradient`	`boolean`	`false`	Enable gradient color selection.
`mode`	`'solid' \| 'gradient'`	—	Presentation or editing mode.
`open`	`boolean`	—	Control whether the panel is open.
`defaultOpen`	`boolean`	—	Initial open state.
`disabled`	`boolean`	`false`	Disable interaction.
`name`	`string`	—	Field name in native FormData.
`form`	`string`	—	ID of the associated native form.

ColorPreset

Property	Type	Default	Description
`label`	`ReactNode`	—	Required. Group heading
`colors`	`readonly string[]`	—	Required. Color values in the group

Types

Import these types to define props or prepare data.

import type { ColorPickerProps, ColorPreset } from '@ifhover/leaf-ui';

Usage notes

Colors are strings; HEX may contain eight digits when opacity is enabled. Changing format preserves the submitted value; the next adjustment outputs the selected format. onChange reports live changes, while onChangeComplete reports pointer release, keyboard adjustment, input submission or preset selection.

Use arrow keys in the color plane, with Shift for larger steps. Left/right adjust saturation; up/down adjust brightness. Enter or blur submits color text; invalid text displays an error. Supports FormData, required validation and uncontrolled form reset. Reset controlled state in your application.

ColorGradient

Property	Type	Default	Description
`angle`	`number`	—	Required. Gradient angle in degrees.
`stops`	`readonly ColorGradientStop[]`	—	Required. Color stops in the gradient.

ColorGradientStop

Property	Type	Default	Description
`key`	`string`	—	Stable, unique identifier.
`color`	`string`	—	Required. Color or semantic tone.
`offset`	`number`	—	Required. Offset; color stops use a percentage from 0 to 100.

#ColorPicker

#Choose a color

#Formats and transparency

#Presets and states

#Gradients

#ColorPicker API

#ColorPreset

#Types

#Usage notes

#ColorGradient

#ColorGradientStop