Color Picker
Allows users to select any color using a dedicated Color Picker interface.
<script setup lang="ts">import { VColorPicker } from '@vonage/vivid-api-vue';</script>
<template> <VColorPicker label="Primary color" /></template>import '@vonage/vivid-api/color-picker';or, if you need to use a unique prefix:
import { registerColorPicker' } from '@vonage/vivid-api';
registerColorPicker('your-prefix');<script type="module"> import { registerColorPicker } from '@vonage/vivid-api'; registerColorPicker('your-prefix');</script>
<your-prefix-color-picker label="Primary color"></your-prefix-color-picker>Use the open attribute to indicate whether the Simple Color Picker’s popup should be open.
- Type:
boolean - Default:
false
<script setup lang="ts">import { VColorPicker } from '@vonage/vivid-api-vue';</script><template> <VColorPicker label="Primary color" saved-colors-key="vvd-color-picker-open" open /></template><vwc-color-picker label="Primary color" saved-colors-key="vvd-color-picker-open" open></vwc-color-picker>Saved colors are stored in the browser’s localStorage by default, using a key generated from the component’s tag name.
To ensure persistence and uniqueness, it’s good practice to specify a custom key using the saved-colors-key attribute.
<script setup lang="ts"> import {VColorPicker} from '@vonage/vivid-api-vue';</script><template> <VColorPicker label="Primary color" saved-colors-key="vvd-color-picker-unique-key" /></template><vwc-color-picker label="Primary color" saved-colors-key="vvd-color-picker-unique-key"></vwc-color-picker>You can use the disabled-saved-colors attribute to disable saving colors by the users.
- Type:
boolean - Default:
false
<script setup lang="ts"> import {VColorPicker} from '@vonage/vivid-api-vue';</script><template> <VColorPicker label="Primary color" disable-saved-colors /></template><vwc-color-picker label="Primary color" disable-saved-colors></vwc-color-picker>The contextual-help slot allows you to add the Contextual Help component next to the label.
<script setup lang="ts">import { VContextualHelp, VColorPicker } from '@vonage/vivid-api-vue';</script><template> <VColorPicker label="Color Picker" saved-colors-key="vvd-color-picker-contextual-help"> <template #contextual-help><VContextualHelp>Choose your brand color</VContextualHelp></template> </VColorPicker></template><vwc-color-picker label="Color Picker" saved-colors-key="vvd-color-picker-contextual-help"> <vwc-contextual-help slot="contextual-help">Choose your brand color</vwc-contextual-help></vwc-color-picker>The helper-text slot allows you to use rich content as the Color Picker’s helper text.
<script setup lang="ts">import { VColorPicker } from '@vonage/vivid-api-vue';</script><template> <VColorPicker label="Primary color" saved-colors-key="vvd-color-picker-helper-text"> <template #helper-text><span>Choose the Primary Color</span></template> </VColorPicker></template><vwc-color-picker label="Primary color" saved-colors-key="vvd-color-picker-helper-text"> <span slot="helper-text">Choose the Primary Color</span></vwc-color-picker>The popup-text slot allows you to override the default “Color Picker” title displayed in the Color Picker’s popup.
<script setup lang="ts">import { VColorPicker } from '@vonage/vivid-api-vue';</script><template> <VColorPicker label="Primary color" saved-colors-key="vvd-color-picker-popup-text"> <template #popup-text><span>Brand Color</span></template> </VColorPicker></template><vwc-color-picker label="Primary color" saved-colors-key="vvd-color-picker-popup-text"> <span slot="popup-text">Brand Color</span></vwc-color-picker>The swatches-text slot allows you to override the default “Saved Colors:” text displayed above the color swatches.
<script setup lang="ts">import { VColorPicker } from '@vonage/vivid-api-vue';
const swatches = [{label: 'Magenta',value: '#D6219C',},{label: 'Blue',value: '#80C7F5',},{label: 'Orange',value: '#FA7454',},{label: 'Peach',value: '#FCAC98',},];
</script><template> <VColorPicker :swatches="swatches" label="Brand color" value="#D6219C" disable-saved-colors> <template #swatches-text><span>Brand Colors:</span></template> </VColorPicker></template><vwc-color-picker id="picker" label="Brand color" value="#D6219C" disable-saved-colors> <span slot="swatches-text">Brand Colors:</span></vwc-color-picker>
<script> const swatches = [ { label: 'Magenta', value: '#D6219C', }, { label: 'Blue', value: '#80C7F5', }, { label: 'Orange', value: '#FA7454', }, { label: 'Peach', value: '#FCAC98', }, ];
const picker = document.getElementById('picker'); picker.swatches = swatches;</script>| Property | Type | Default | Description |
|---|---|---|---|
| disableSavedColors | boolean | Disables the saving colors functionality | |
| disabled | boolean | Sets the element's disabled state. A disabled element will not be included during form submission. | |
| errorText | string | Provides a custom error message. Any current error state will be overridden. | |
| helperText | string | Provides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead. | |
| initialValue | string | The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set. | |
| label | string | The label for the form element. | |
| maxSwatches | number | Limits number of swatches that can be saved. | |
| name | string | The name of the element. This element's value will be surfaced during form submission under the provided name. | |
| open | boolean | Indicates whether the popup is open | |
| placeholder | string | Text that appears in the input element when it has no value set | |
| required | boolean | Require the field to be completed prior to form submission. | |
| savedColorsKey | string | Sets the localStorage key used to store saved colors explicitly | |
| successText | string | Provides a custom success message. Any current error state will be overridden. | |
| swatches | {label?: string; value: string}[] | List of color swatches, has to be an array of objects | |
| value (modelValue) | string | The current value of the element. |
| Property | Type | Default | Description |
|---|---|---|---|
| disable-saved-colors | boolean | Disables the saving colors functionality | |
| disabled | boolean | Sets the element's disabled state. A disabled element will not be included during form submission. | |
| error-text | string | Provides a custom error message. Any current error state will be overridden. | |
| helper-text | string | Provides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead. | |
| value | string | The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set. | |
| label | string | The label for the form element. | |
| max-swatches | number | Limits number of swatches that can be saved. | |
| name | string | The name of the element. This element's value will be surfaced during form submission under the provided name. | |
| open | boolean | Indicates whether the popup is open | |
| placeholder | string | Text that appears in the input element when it has no value set | |
| required | boolean | Require the field to be completed prior to form submission. | |
| saved-colors-key | string | Sets the localStorage key used to store saved colors explicitly | |
| success-text | string | Provides a custom success message. Any current error state will be overridden. | |
| swatches (property only) | {label?: string; value: string}[] | List of color swatches, has to be an array of objects | |
| current-value | string | The current value of the element. |
| Name | Description |
|---|---|
| contextual-help | Slot for the contextual-help component, displayed next to the label. |
| helper-text | Describes how to use the text-field. Alternative to the `helper-text` attribute. |
| popup-text | Overrides the default "Color Picker" title of the Popup window. |
| swatches-text | Overrides the default "Saved colors:" text above color swatches. |
| Name | Description |
|---|---|
| contextual-help | Slot for the contextual-help component, displayed next to the label. |
| helper-text | Describes how to use the text-field. Alternative to the `helper-text` attribute. |
| popup-text | Overrides the default "Color Picker" title of the Popup window. |
| swatches-text | Overrides the default "Saved colors:" text above color swatches. |
| Name | Type | Description |
|---|---|---|
| change | CustomEvent<undefined> | Fires when the value changes |
| input | Event | Fires when the value of the element changes. |
| Name | Type | Description |
|---|---|---|
| change | CustomEvent<undefined> | Fires when the value changes |
| input | Event | Fires when the value of the element changes. |
| Name | Params | Returns | Description |
|---|---|---|---|
| checkValidity | boolean | Return the current validity of the element. | |
| reportValidity | boolean | Return the current validity of the element. If false, fires an invalid event at the element. |