ColorPicker
Used for color selection.
When To Use
Used when the user needs to make a customized color selection.
Examples
-
Basic Usage ·
base -
Trigger size ·
size -
controlled mode ·
controlled -
Line Gradient ·
line-gradient -
Rendering Trigger Text ·
text-render -
Disable ·
disabled -
Disabled Alpha ·
disabled-alpha -
Clear Color ·
allowClear -
Custom Trigger ·
trigger -
Custom Trigger Event ·
trigger-event -
Color Format ·
format -
Preset Colors ·
presets -
Custom Render Panel ·
panel-render -
Custom semantic dom styling ·
style-class
API
Common props ref：Common props
This component is available since
antd@5.5.0.
| Property | Description | Type | Default | Version | Global Config |
|---|---|---|---|---|---|
| allowClear | Allow clearing color selected | boolean | false | × | |
| arrow | Configuration for popup arrow | boolean | { pointAtCenter: boolean } | true | 6.3.0 | |
| children | Trigger of ColorPicker | React.ReactNode | - | × | |
| classNames | Customize class for each semantic structure inside the component. Supports object or function. | Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string> | - | 6.0.0 | |
| defaultValue | Default value of color | ColorType | - | × | |
| defaultFormat | Default format of color | rgb | hex | hsb | hex | 5.9.0 | × |
| disabled | Disable ColorPicker | boolean | - | × | |
| disabledAlpha | Disable Alpha | boolean | - | 5.8.0 | × |
| disabledFormat | Disable format of color | boolean | - | 5.22.0 | × |
| Whether destroy dom when close | boolean | false | 5.7.0 | × | |
| destroyOnHidden | Whether destroy dom when close | boolean | false | 5.25.0 | × |
| format | Format of color | rgb | hex | hsb | - | × | |
| mode | Configure single or gradient color | 'single' | 'gradient' | ('single' | 'gradient')[] | single | 5.20.0 | × |
| open | Whether to show popup | boolean | - | × | |
| presets | Preset colors | PresetColorType | - | × | |
| placement | Placement of popup | The design of the placement parameter is the same as the Tooltips component. | bottomLeft | × | |
| panelRender | Custom Render Panel | (panel: React.ReactNode, extra: { components: { Picker: FC; Presets: FC } }) => React.ReactNode | - | 5.7.0 | × |
| showText | Show color text | boolean | (color: Color) => React.ReactNode | - | 5.7.0 | × |
| size | Setting the trigger size | large | medium | small | medium | 5.7.0 | × |
| styles | Customize inline style for each semantic structure inside the component. Supports object or function. | Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties> | - | 6.0.0 | |
| trigger | ColorPicker trigger mode | hover | click | click | × | |
| value | Value of color | ColorType | - | × | |
| onChange | Callback when value is changed | (value: Color, css: string) => void | - | × | |
| onChangeComplete | Called when color pick ends. Will not change the display color when value controlled by onChangeComplete | (value: Color) => void | - | 5.7.0 | × |
| onFormatChange | Callback when format is changed | (format: 'hex' | 'rgb' | 'hsb') => void | - | × | |
| onOpenChange | Callback when open is changed | (open: boolean) => void | - | × | |
| onClear | Called when clear | () => void | - | 5.6.0 | × |
ColorType
type ColorType =
| string
| Color
| {
color: string;
percent: number;
}[];
PresetColorType
type PresetColorType = {
label: React.ReactNode;
defaultOpen?: boolean;
key?: React.Key;
colors: ColorType[];
};
Color
| Property | Description | Type | Version |
|---|---|---|---|
| toCssString | Convert to CSS support format | () => string | 5.20.0 |
| toHex | Convert to hex format characters, the return type like: 1677ff | () => string | - |
| toHexString | Convert to hex format color string, the return type like: #1677ff | () => string | - |
| toHsb | Convert to hsb object | () => ({ h: number, s: number, b: number, a: number }) | - |
| toHsbString | Convert to hsb format color string, the return type like: hsb(215, 91%, 100%) | () => string | - |
| toRgb | Convert to rgb object | () => ({ r: number, g: number, b: number, a: number }) | - |
| toRgbString | Convert to rgb format color string, the return type like: rgb(22, 119, 255) | () => string | - |
Semantic DOM
| Semantic node | Native description | Version |
|---|---|---|
root | Trigger container with border styles, transition animations, size controls, displaying color block and text content | — |
body | Color block container with background color, border styles | — |
content | Color block element with actual selected color styles | — |
description | Description text content with font styles and color | — |
popup.root | Popup panel root container with background color, shadow effects, color selection panel, slider controls and preset colors | — |
Semantic description source: vendor/components/color-picker/demo/_semantic.tsx
FAQ
Questions about color assignment
The value of the color selector supports both string color values and selector-generated Color objects. However, since there is a precision error when converting color strings of different formats to each other, it is recommended to use selector-generated Color objects for assignment operations in controlled scenarios, so that the precision problem can be avoided and the values are guaranteed to be accurate and the selector can work as expected.
Shared native props
Tips: The following generic properties apply to most antd components; those not supported are described separately.
| Property | Description | Type | Default |
|---|---|---|---|
| style | The additional style | CSSProperties | - |
| className | The additional css class | string | - |
| rootClassName | ClassName on the root element | string | - |
| autoFocus | Auto focus when component mounted, only effective for focusable elements like forms, links, etc. | boolean | false |
Install and reproduce an example
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
Use ConfigProvider and native App; configure dayjs locale separately. Each example lists its complete source files and additional pinned dependencies in View code. Example names select demos, not universal component props. See the resource setup guide for theme, locale and SSR.
Native type references
The source viewer includes unchanged native implementations and the following source declarations. Inherited types remain in their native packages. English source comments are preserved as code reference.
vendor/components/color-picker/ColorPicker.tsxvendor/components/color-picker/ColorPickerPanel.tsxvendor/components/color-picker/color.tsvendor/components/color-picker/components/ColorAlphaInput.tsxvendor/components/color-picker/components/ColorClear.tsxvendor/components/color-picker/components/ColorHexInput.tsxvendor/components/color-picker/components/ColorHsbInput.tsxvendor/components/color-picker/components/ColorInput.tsxvendor/components/color-picker/components/ColorPresets.tsxvendor/components/color-picker/components/ColorRgbInput.tsxvendor/components/color-picker/components/ColorSlider.tsxvendor/components/color-picker/components/ColorSteppers.tsxvendor/components/color-picker/components/ColorTrigger.tsxvendor/components/color-picker/components/PanelPicker/GradientColorBar.tsxvendor/components/color-picker/components/PanelPicker/index.tsxvendor/components/color-picker/context.tsvendor/components/color-picker/hooks/useModeColor.tsvendor/components/color-picker/interface.tsvendor/components/color-picker/style/index.ts
Source and license
https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd
Original bilingual prose and executable examples are retained. Website-only embeds and token tables are expanded locally. Ant Design is MIT; separately listed dependency notices also apply. Upload previews block outbound requests and do not provide a backend.