> 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-picker.md).

# 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, predefined swatches, or design tokens.

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.
* **Design tokens:** Bind selections to design system tokens.
* **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.          |
| `tokens`     | Bind selections to design system tokens.              |

***

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

```html
<!-- 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>
```

```js
// 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.

```html
<!-- 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.                        |

### 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 <support@avonni.app> 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-picker.md?ask=<question>&goal=<endgoal>
```

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