> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/color-palette.md).
# 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.
```html
```
```js
// 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 = event.detail.value;
}
}
```
**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.
```html
```
```js
// 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. |
### 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 for assistance.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.avonnicomponents.com/lwc-components/core-components/color-palette.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.