> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/color-picker.html
> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.
# 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.
**#20834aCurrent color：#20834a
basic.tsx
Copy code
```tsx lineNumbers file="../../../src/examples/en/color-picker/basic.tsx"
import { ColorPicker, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function ColorPickerBasic() {
const [color, setColor] = useState('#20834a');
return (
Current color：{color}
);
}
```
Expand code
## Formats and transparency
HEX**#1677ff
RGB · Transparent**rgba(118, 84, 198, 0.6)
HSL · Opaque**hsl(35, 91%, 55%)
formats.tsx
Copy code
```tsx lineNumbers file="../../../src/examples/en/color-picker/formats.tsx"
import { ColorPicker, Flex, Text } from '@ifhover/leaf-ui';
export function ColorPickerFormats() {
return (
HEX
RGB · Transparent
HSL · Opaque
);
}
```
Expand code
## Presets and states
Custom presets · Clearable**#20834a
Disabled**#1677ff
presets.tsx
Copy code
```tsx lineNumbers file="../../../src/examples/en/color-picker/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 (
Custom presets · Clearable
Disabled
);
}
```
Expand code
## Gradients
Solid color**#20834a
Gradient: select, add or remove stops**Gradient
capabilities.tsx
Copy code
```tsx lineNumbers file="../../../src/examples/color-picker/capabilities.tsx"
import { ColorPicker, Flex, Space, Text } from '@ifhover/leaf-ui';
export function Capabilities() {
return (
{'Solid color'}
{'Gradient: select, add or remove stops'}
);
}
```
Expand code
## 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`](#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.
```ts
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`](#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. |