Color Picker

Allows users to select any color using a dedicated Color Picker interface.

Labelling

Label Text

The label attribute provides a short description of the purpose of the Color Picker.

If a visible label can’t be used, provide one using the

aria-label

attribute. This ensures screen readers announce the purpose of the element, making it accessible to all users.

Helper Text

The helper-text attribute provides additional information about the purpose of the Color Picker.
To add HTML to the helper text, use the helper-text slot.

<script setup lang="ts">
  import {VColorPicker} from '@vonage/vivid-api-vue';
</script>
<template>
  <VColorPicker label="Primary color" helper-text="Use the HEX color code (e.g. #ffffff)" saved-colors-key="vvd-color-picker-helper-text" />
</template>

Placeholder Text

The placeholder attribute provides some text to be displayed when no color is selected.

<script setup lang="ts">
  import {VColorPicker} from '@vonage/vivid-api-vue';
</script>
<template>
  <VColorPicker label="Color Picker with Placeholder" placeholder="#ffffff" saved-colors-key="vvd-color-picker-placeholder" />
</template>

Contextual Help

You can add the Contextual Help component using the contextual-help slot. It will be displayed next to the label, providing users additional information.

<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>

Validation Feedback

Error Text

The error-text attribute provides a custom error message. Any current error state will be overridden by error-text.

<script setup lang="ts">
  import {VColorPicker} from '@vonage/vivid-api-vue';
</script>
<template>
  <VColorPicker label="Color Picker" value="example" saved-colors-key="vvd-color-picker-error" error-text="This is not a correct HEX color" />
</template>

Success Text

The success-text attribute provides a custom success message. Any current error state will be overridden by success-text.

Value

The value attribute can be used to set the default value for the Color Picker element.

<script setup lang="ts">
  import {VColorPicker} from '@vonage/vivid-api-vue';
</script>
<template>
  <VColorPicker label="Primary color" value="#D6219C" saved-colors-key="vvd-color-picker-value" />
</template>

Swatches

The swatches attribute can be used to set the default color palette that will be displayed in the Color Picker’s Popup.

It accepts an array of objects with value and label properties: [{"label": "Red", "value": "#ff0000"}, {"value": "#00ff00"}]. The optional label property provides descriptive text for screen readers, improving accessibility.

<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="Primary color" value="#D6219C" saved-colors-key="vvd-color-picker-swatches" />
</template>

<vwc-color-picker id="picker" label="Primary color" value="#D6219C" saved-colors-key="vvd-color-picker-swatches"></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>

Max Swatches

The maximum number of displayed color swatches (either saved by the user or passed using swatches attribute) can be set using the max-swatches attribute.

<script setup lang="ts">
import { VColorPicker } from '@vonage/vivid-api-vue';
</script>
<template>
  <VColorPicker label="Primary color" :max-swatches="4" saved-colors-key="vvd-color-picker-max-swatches" />
</template>

Swatches Text

The default “Saved Colors:” text displayed above the color swatches can be overridden with swatches-text slot.

<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>

Disabled

The disabled attribute disables the Color Picker element.