---
title: Color Picker 颜色选择器
---

# Color Picker 颜色选择器

ColorPicker is a color selector supporting multiple color formats.

## Basic usage

:::example ColorPicker requires a string typed variable to be bound to v-model.

color-picker/basic

:::

## Alpha

:::example ColorPicker supports alpha channel selecting. To activate alpha selecting, just add the `show-alpha` attribute.

color-picker/alpha

:::

## Predefined colors

:::example ColorPicker supports predefined color options

color-picker/predefined-color

:::

## Sizes

:::example

color-picker/sizes

:::

## API

### Attributes

| Name                        | Description                                                                                        | Type                                                                                                  | Default                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| model-value / v-model       | binding value                                                                                      | ^[string]                                                                                             | —                                                                            |
| disabled                    | whether to disable the ColorPicker                                                                 | ^[boolean]                                                                                            | false                                                                        |
| clearable ^(2.13.1)         | whether to show clear button                                                                       | ^[boolean]                                                                                            | true                                                                         |
| size                        | size of ColorPicker                                                                                | ^[enum]`'large' \| 'default' \| 'small'`                                                              | —                                                                            |
| show-alpha                  | whether to display the alpha slider                                                                | ^[boolean]                                                                                            | false                                                                        |
| color-format                | color format of v-model                                                                            | ^[enum]`'rgb' \| 'prgb' \| 'hex' \| 'hex3' \| 'hex4' \| 'hex6' \| 'hex8' \| 'name' \| 'hsl' \| 'hsv'` | ^[enum]`'hex' (when show-alpha is false) \| 'rgb' (when show-alpha is true)` |
| popper-class                | custom class name for ColorPicker's dropdown                                                       | ^[string] / ^[object]                                                                                 | ''                                                                           |
| popper-style ^(2.11.4)      | custom style for ColorPicker's dropdown                                                            | ^[string] / ^[object]                                                                                 | —                                                                            |
| predefine                   | predefined color options                                                                           | ^[array]`string[]`                                                                                    | —                                                                            |
| validate-event              | whether to trigger form validation                                                                 | ^[boolean]                                                                                            | true                                                                         |
| tabindex                    | ColorPicker tabindex                                                                               | ^[string] / ^[number]                                                                                 | 0                                                                            |
| aria-label ^(a11y) ^(2.7.2) | ColorPicker aria-label                                                                             | ^[string]                                                                                             | —                                                                            |
| empty-values ^(2.10.3)      | empty values of component, [see config-provider](/docs/component/config-provider#empty-values-configurations) | ^[array]                                                                                              | —                                                                            |
| value-on-clear ^(2.10.3)    | clear return value, [see config-provider](/docs/component/config-provider#empty-values-configurations)        | ^[string] / ^[number] / ^[boolean] / ^[Function]                                                      | —                                                                            |
| id                          | ColorPicker id                                                                                     | ^[string]                                                                                             | —                                                                            |
| teleported ^(2.7.2)         | whether color-picker popper is teleported to the body                                              | ^[boolean]                                                                                            | true                                                                         |
| label ^(a11y) ^(deprecated) | ColorPicker aria-label                                                                             | ^[string]                                                                                             | —                                                                            |
| persistent ^(2.10.5)        | when color-picker inactive and persistent is false, the color panel will be destroyed              | ^[boolean]                                                                                            | true                                                                         |
| append-to ^(2.10.5)         | which element the color-picker panel appends to                                                    | ^[CSSSelector] / ^[HTMLElement]                                                                       | -                                                                            |

### Events

| Name            | Description                                    | Type                                     |
| --------------- | ---------------------------------------------- | ---------------------------------------- |
| change          | triggers when input value changes              | ^[Function]`(value: string) => void`     |
| active-change   | triggers when the current active color changes | ^[Function]`(value: string) => void`     |
| focus ^(2.4.0)  | triggers when Component focuses                | ^[Function]`(event: FocusEvent) => void` |
| blur ^(2.4.0)   | triggers when Component blurs                  | ^[Function]`(event: FocusEvent) => void` |
| clear ^(2.13.1) | triggers when the clear button is clicked      | ^[Function]`() => void`                  |

### Exposes

| Name            | Description               | Type                    |
| --------------- | ------------------------- | ----------------------- |
| color           | current color object      | ^[object]`Color`        |
| show ^(2.3.3)   | manually show ColorPicker | ^[Function]`() => void` |
| hide ^(2.3.3)   | manually hide ColorPicker | ^[Function]`() => void` |
| focus ^(2.3.13) | focus the picker element  | ^[Function]`() => void` |
| blur ^(2.3.13)  | blur the picker element   | ^[Function]`() => void` |