Color Palette

avonni-color-palette

Displays a palette of predefined color swatches for the user to choose from.

Overview

Color Palette is a Lightning Web Component that displays a set of preset color tiles—optionally grouped—from which users pick a single color.

Use it in your own Lightning Web Components to offer a curated set of brand or theme colors rather than a free-form picker. You control the colors, grouping, layout (grid or list), tile size, selection indicators, and read-only or disabled states—all through the component's attributes.

Use Cases

• Brand palettes: Restrict selection to approved brand colors.
• Theme settings: Let users pick a theme accent from a curated set.
• Category coloring: Assign a color to a record or label from presets.
• Grouped swatches: Organize colors into named groups (brand, neutral, etc.).
• Compact pickers: Show a tight grid of swatches in a sidebar or popover.

---

Variant Guidelines

Variant	Use Case
grid	Compact swatch grids; pair with columns and tile sizes.
list	Labeled rows, ideal when colors are grouped.

---

Use Case Examples

Example 1: Grouped brand palette

Scenario: Show brand and neutral colors as labeled rows with a checkmark on the selection.

<!-- brandPalette.html -->
<template>
    <avonni-color-palette
        colors={colors}
        groups={groups}
        value={value}
        variant="list"
        columns="4"
        tile-width="28"
        tile-height="28"
        show-checkmark
        onchange={handleChange}
    ></avonni-color-palette>
</template>

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

export default class BrandPalette extends LightningElement {
    groups = [
        { name: 'brand', label: 'Brand' },
        { name: 'neutral', label: 'Neutrals' }
    ];
    colors = [
        { label: 'Brand Primary', value: 'brand-primary', color: '#1b96ff', groups: ['brand'] },
        { label: 'Brand Accent', value: 'brand-accent', color: '#9050e9', groups: ['brand'] },
        { label: 'Ink', value: 'neutral-ink', color: '#181818', groups: ['neutral'] },
        { label: 'Paper', value: 'neutral-paper', color: '#f3f3f3', groups: ['neutral'] }
    ];
    value = 'brand-primary';

    handleChange(event) {
        const { label, hex, token } = event.detail;
        this.value = token; // the selected color's value is carried in `token`
    }
}

Result: A grouped, labeled list of swatches with the selected color checkmarked; selecting a tile fires change with its label, hex, and token.

Example 2: Compact swatch grid

Scenario: Offer a tight grid of preset colors as plain hex strings.

<!-- swatchGrid.html -->
<template>
    <avonni-color-palette
        colors={colors}
        variant="grid"
        columns="5"
        onchange={handleChange}
    ></avonni-color-palette>
</template>

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

export default class SwatchGrid extends LightningElement {
    colors = ['#1b96ff', '#9050e9', '#3bba4c', '#fe9339', '#c23934'];

    handleChange(event) {
        const hex = event.detail.hex;
    }
}

Result: A five-column grid of color tiles; clicking one fires change with the selected hex value.

---

Specifications

Attributes

Name	Description	Type	Default	Required
colors	Array of colors displayed in the default palette. Each color can either be a string or a color object.	string	AvonniColorPaletteColor[]	"“#e3abec”, “#c2dbf7”, ”#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	Specifies the number of columns displayed. If unspecified, the tiles spread to the width of the container.	Number	—
disabled	If present, the input field is disabled and users cannot interact with it.	Boolean	false
groups	Array of group objects.	AvonniColorPaletteGroup[]	—
hide-outline	If present, the selected outline is hidden.	Boolean	false
is-loading	If present, a spinner is displayed to indicate that data is loading.	Boolean	false
loading-state-alternative-text	Message displayed while the palette is in the loading state.	String	"Loading..."
read-only	If present, the palette is read-only and cannot be edited by users.	Boolean	false
show-checkmark	If present, the selected checkmark is shown.	Boolean	false
tile-height	Tile height in px.	Number	20
tile-width	Tile width in px.	Number	20
value	Specifies the value of an input element.	String	—
variant	Changes the appearance of the palette. Valid values include grid and list.	String	"grid"

Methods

Name	Description	Argument Name	Argument Type	Argument Description
focus	Set the focus on the first palette item.
reset	Clear the value.

Custom Events

blur

The event fired when the focus is removed from the palette.

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 value is 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.
label	string	Color label.
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.

colordblclick

The event fired when a color is clicked twice.

The colordblclick event doesn't return any parameters.

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

focus

The event fired when the focus is set on the palette.

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

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 value is 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.
label	string	Color label.
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.

colordblclick

The event fired when a color is clicked twice.

The colordblclick event doesn't return any parameters.

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

focus

The event fired when the focus is set on the palette.

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-palette-swatch-border-radius	dimension	0.125rem
--avonni-color-palette-swatch-selected-outline-width	dimension	2px
--avonni-color-palette-swatch-selected-outline-color	color	dynamic (swatch background-color)
--avonni-color-palette-swatch-selected-border-width	dimension	1px
--avonni-color-palette-swatch-selected-border-color	color	white
--avonni-color-palette-swatch-selected-checkmark-color	color	dynamic (white or black depending on the background color)

Key Considerations

• Color objects vs. strings: Objects let you return a label and token in the change event; plain hex strings return only color formats.
• Grouping: Provide groups and tag each color with a groups array to organize swatches—pairs well with variant="list".
• Selection indicators: Use show-checkmark and/or the outline (toggle off with hide-outline) to indicate the active color.
• Double-click: Listen for colordblclick to support a quick confirm/apply gesture.
• Loading state: Set is-loading with loading-state-alternative-text while fetching colors.
• Best Practice: Use color objects with value, label, and groups (rather than plain hex strings) so the change event can return a meaningful label and token alongside the hex value.

---

Troubleshooting Common Issues

• Labels missing from events: Use color objects with label/value rather than plain hex strings to populate the change detail.
• No selection indicator: Enable show-checkmark or leave hide-outline off so the active tile is marked.
• Colors not grouped: Confirm each color's groups array references a name defined in the groups attribute.
• If issues persist: Contact our support team at [email protected] for assistance.