Color Picker

avonni-color-picker

A color input that lets users select a color from a palette, a gradient or a custom value.

Overview

Color Picker is a Lightning Web Component that lets users choose a color from a palette, a custom hex/RGB selector, or a set of predefined swatches.

Use it in your own Lightning Web Components to capture a color value for branding, theming, or styling configuration. You control the palette colors, the picker type, the menu appearance, opacity support, and validation—all through the component's attributes.

Use Cases

• Brand configuration: Let users set a primary or accent color for a theme.
• Custom styling: Capture a background or text color for a record or layout.
• Predefined palettes: Restrict choices to an approved set of swatches.
• Inline pickers: Embed the palette directly on the page without a popover.

---

Type Guidelines

Type	Use Case
base	Full picker with tabs for default palette and custom.
custom	Free-form hex/RGB selection only.
predefined	Restrict to a fixed set of palette swatches.

---

Use Case Examples

Example 1: Brand color from a palette

Scenario: Let users pick a brand color from a constrained set of swatches and read the selected hex value.

<!-- brandColor.html -->
<template>
    <avonni-color-picker
        label="Brand color"
        field-level-help="Pick a color from the palette or enter a custom hex value."
        type="base"
        columns="6"
        colors={colors}
        value={selectedColor}
        menu-variant="border-filled"
        required
        onchange={handleChange}
    ></avonni-color-picker>
</template>

// brandColor.js
import { LightningElement } from 'lwc';

export default class BrandColor extends LightningElement {
    colors = ['#1b96ff', '#00aea9', '#3bba4c', '#f4bc25', '#f99120', '#bd35bd'];
    selectedColor = '#1b96ff';

    handleChange(event) {
        const hex = event.detail.hex; // e.g. '#3bba4c'
    }
}

Result: A color picker showing a six-column palette; selecting a swatch fires change with the chosen color in multiple formats.

Example 2: Inline predefined palette

Scenario: Show a fixed palette directly on the page (no popover) and hide the hex input field.

<!-- highlightPicker.html -->
<template>
    <avonni-color-picker
        label="Highlight"
        type="predefined"
        inline
        hide-color-input
        colors={colors}
        value="#3bba4c"
        onchange={handleChange}
    ></avonni-color-picker>
</template>

Result: An inline palette of approved swatches with no popover or hex field; clicking a swatch fires change with the selected color.

---

Specifications

Attributes

Name	Description	Type	Default	Required
access-key	Specifies a shortcut key to activate or focus an element.	String	—
cancel-button-label	The label for the cancel button.	String	"Cancel"
colors	Array of colors displayed in the default palette. Each color can either be a string, or a color object. The color objects are used in conjunction with the groups attribute, to split the colors into different groups.	string	AvonniColorPickerColor[]	"“#e3abec”, “#c2dbf6”, ”#9fd6ff”, ”#9de7da”, ”#9df0bf”, ”#fff099”, ”#fed49a”, ”#d073df”, ”#86b9f3”, ”#5ebbff”, ”#44d8be”, ”#3be281”, ”#ffe654”, ”#ffb758”, ”#bd35bd”, ”#5778c1”, ”#1b96ff”, ”#00aea9”, ”#3bba4c”, ”#f4bc25”, ”#f99120”, ”#580d8c”, ”#001870”, ”#0a2399”, ”#097476”, ”#096a50”, ”#b67d11”, ”#b85d0d”"
columns	Number of columns in the palette. If unspecified, defaults to 7 except when inline is present.	Number	7
custom-tab-label	The label for the custom tab.	String	"Custom"
default-tab-label	The label for the default tab.	String	"Default"
disabled	If present, the input field is disabled and users cannot interact with it.	Boolean	false
done-button-label	The label for the done button.	String	"Done"
field-level-help	Help text detailing the purpose and function of the input.	String	—
groups	Array of group objects. Groups can be used by the tokens and the predefined palette.	AvonniColorPickerGroup[]	—
hide-clear-icon	If present, it is not possible to clear a selected color using the input clear icon.	Boolean	false
hide-color-input	If present, hide the input color value.	Boolean	false
inline	If present, the popover is deactivated and its content is directly shown on the page.	Boolean	false
is-loading	If present, a spinner is displayed to indicate that data is loading.	Boolean	false
label	Text label for the input.	String	—	Yes
loading-state-alternative-text	Message displayed while the color picker is in the loading state.	String	"Loading..."
menu-alignment	Determines the alignment of the menu relative to the button. Available options are: auto, left, center, right, bottom-left, bottom-center, bottom-right. The auto option aligns the dropdown menu based on available space.	String	"left"
menu-icon-name	The Lightning Design System name of the icon to use as a button icon, instead of the color dropdown. Names are written in the format 'standard:account' where 'standard' is the category, and 'account' is the specific icon to be displayed.	String	—
menu-icon-size	Size of the icon. Options include xx-small, x-small, small, medium, or large.	String	"x-small"
menu-label	Optional text to be shown on the button.	String	—
menu-nubbin	If present, a nubbin is present on the menu. A nubbin is a stub that protrudes from the menu item towards the button menu. The nubbin position is based on the menu-alignment.	Boolean	false
menu-variant	The variant changes the look of the button. Accepted variants include bare, container, border, border-filled, bare-inverse, and border-inverse.	String	"border"
message-when-bad-input	Error message to be displayed when a bad input is detected.	String	—
message-when-value-missing	Error message to be displayed when the value is missing and input is required.	String	—
name	Specifies the name of an input element.	String	—
opacity	If present, the alpha slider will be displayed.	Boolean	false
palette-hide-outline	If present, the selected palette swatch outline is hidden.	Boolean	false
palette-show-checkmark	If present, the selected palette swatch shows a checkmark.	Boolean	false
read-only	If present, the input field is read-only and cannot be edited by users.	Boolean	false
required	If present, the input field must be filled out before the form is submitted.	Boolean	false
required-alternative-text	The assistive text when the required attribute is set to true.	String	"Required"
type	Type of the color picker. The base type uses tabs for all the other types. Valid values include base, custom, predefined and tokens.	String	"base"
validity	Represents the validity states that an element can be in, with respect to constraint validation.	String	—
value	Specifies the value of an input element.	String	—
variant	The variant changes the appearance of an input field. Accepted variants include standard, label-inline, label-hidden, and label-stacked. This value defaults to standard, which displays the label above the field. Use label-hidden to hide the label but make it available to assistive technology. Use label-inline to horizontally align the label and input field. Use label-stacked to place the label above the input field.	String	"standard"

Methods

Name	Description	Argument Name	Argument Type	Argument Description
blur	Removes keyboard focus from the input element.
checkValidity	Checks if the input is valid.
focus	Sets focus on the input element.
reportValidity	Displays the error messages. If the input is valid, reportValidity() clears displayed error messages.
setCustomValidity	Sets a custom error message to be displayed when a form is submitted.	message	String	The string that describes the error. If message is an empty string, the error message is reset.
showHelpMessageIfInvalid	Displays error messages on invalid fields. An invalid field fails at least one constraint validation and returns false when checkValidity() is called.

Custom Events

blur

The event fired when the focus is removed from the color picker input.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

change

The event fired when the color value changed.

The change event returns the following parameters.

Parameter	Type	Description
hex	string	Color in hexadecimal format.
hexa	string	Color in hexadecimal format with alpha.
rgb	string	Color in rgb format.
rgba	string	Color in rgba format.
alpha	string	Alpha value of the color.
token	string	Token value.

The event properties are as follows.

Property	Value	Description
bubbles	true	This event bubbles up through the DOM.
cancelable	true	This event can be canceled. You can call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

focus

The event fired when the focus is set on the color picker.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

blur

The event fired when the focus is removed from the color picker input.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

change

The event fired when the color value changed.

The change event returns the following parameters.

Parameter	Type	Description
hex	string	Color in hexadecimal format.
hexa	string	Color in hexadecimal format with alpha.
rgb	string	Color in rgb format.
rgba	string	Color in rgba format.
alpha	string	Alpha value of the color.
token	string	Token value.

The event properties are as follows.

Property	Value	Description
bubbles	true	This event bubbles up through the DOM.
cancelable	true	This event can be canceled. You can call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

focus

The event fired when the focus is set on the color picker.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-color-picker-label-text-color	color	#3e3e3c
--avonni-color-picker-label-font-size	font	0.75rem
--avonni-color-picker-label-font-style	font	normal
--avonni-color-picker-label-font-weight	font	400
--avonni-color-picker-swatch-border-radius	dimension	0.125rem
--avonni-color-picker-popover-width	dimension	16rem
--avonni-color-picker-input-width	dimension	195.5px

Key Considerations

• Accessibility: label is required; use variant="label-hidden" to keep it available to assistive technology while hiding it visually.
• Opacity: Set opacity to expose the alpha slider and emit hexa/rgba values in the change detail.
• Constraining choices: Use type="predefined" with a fixed colors array to limit users to approved swatches.
• Inline mode: inline removes the popover and renders the palette in the page flow—ideal for always-visible pickers.
• Best Practice: Always set label for accessibility, and choose the type that matches your needs—use predefined to constrain users to an approved palette and base when both palette and custom selection are allowed.

---

Troubleshooting Common Issues

• No color shows after selection: Confirm the change handler reads event.detail.hex (or hexa when opacity is on) and updates value.
• Custom hex entry unavailable: Use type="base" or type="custom"; predefined only allows palette swatches.
• Palette layout looks wrong: Adjust columns to match the number of colors in your colors array.
• If issues persist: Contact our support team at [email protected] for assistance.