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

# Color Gradient

`avonni-color-gradient`

Lets users pick a color from a gradient surface, with hue and opacity controls.

## Overview

**Color Gradient** is a Lightning Web Component that provides an interactive gradient picker, letting users select a color by saturation, brightness, hue, and optional opacity.

Use it in your own Lightning Web Components to let users choose a precise color— for theming, tagging, or styling settings. You control the current value, whether the opacity slider is shown, read-only and disabled states, and the error message for invalid input—all through the component's attributes.

### Use Cases

* **Theme builders:** Let users pick brand or accent colors for a custom theme.
* **Styling settings:** Capture a color value for a record or configuration.
* **Color tagging:** Assign a color to categories, labels, or events.
* **Design tools:** Provide a fine-grained picker with opacity control.
* **Read-only previews:** Display a previously chosen color without editing.

***

## Use Case Examples

### Example 1: Color picker with opacity

**Scenario:** Let users choose a color with an opacity slider and capture the resulting value in multiple formats.

```html
<!-- themeColorPicker.html -->
<template>
    <avonni-color-gradient
        value={value}
        show-opacity
        message-when-bad-input={messageWhenBadInput}
        onchange={handleChange}
    ></avonni-color-gradient>
</template>
```

```js
// themeColorPicker.js
import { LightningElement } from 'lwc';

export default class ThemeColorPicker extends LightningElement {
    value = '#5867e8';
    messageWhenBadInput = 'Please enter a valid color value.';

    handleChange(event) {
        const { hex, hexa, rgba, alpha } = event.detail;
        this.value = hexa; // includes the alpha channel
    }
}
```

**Result:** A gradient picker with an opacity slider; each adjustment fires `change` with the color in hex, hexa, rgb, and rgba formats plus the alpha value.

### Example 2: Read-only color preview

**Scenario:** Display a previously selected color without allowing edits.

```html
<!-- colorPreview.html -->
<template>
    <avonni-color-gradient value={value} read-only></avonni-color-gradient>
</template>
```

```js
// colorPreview.js
import { LightningElement } from 'lwc';

export default class ColorPreview extends LightningElement {
    value = '#3ba755';
}
```

**Result:** A non-editable gradient showing the stored color.

***

## Specifications

### Attributes

| Name                     | Description                                                                | Type    | Default                            | Required |
| ------------------------ | -------------------------------------------------------------------------- | ------- | ---------------------------------- | -------- |
| `disabled`               | If present, the input field is disabled and users cannot interact with it. | Boolean | —                                  |          |
| `message-when-bad-input` | Error message to be displayed when a bad input is detected.                | String  | `"Please ensure value is correct"` |          |
| `read-only`              | If present, the palette is read-only and cannot be edited by users.        | Boolean | `false`                            |          |
| `show-opacity`           | If present, the opacity slider will be displayed.                          | Boolean | `false`                            |          |
| `value`                  | Specifies the value of an input element.                                   | String  | —                                  |          |

### Methods

| Name    | Description                          | Argument Name | Argument Type | Argument Description |
| ------- | ------------------------------------ | ------------- | ------------- | -------------------- |
| `focus` | Set the focus on the color gradient. |               |               |                      |

### Custom Events

#### `blur`

The event fired when the color gradient loses focus.

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

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

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-gradient-max-width` | dimension | `20rem` |

## Key Considerations

* **Output formats:** `change` provides `hex`, `hexa`, `rgb`, `rgba`, and `alpha`—pick the one your data model expects.
* **Opacity:** Use `hexa` or `rgba` from the event detail when `show-opacity` is enabled to preserve the alpha channel.
* **Read-only vs. disabled:** `read-only` shows the value but blocks editing; `disabled` greys out and deactivates the control.
* **Validation:** `message-when-bad-input` surfaces when an invalid value is supplied.
* **Best Practice:** Enable `show-opacity` only when your downstream usage supports an alpha channel; otherwise the chosen opacity may be discarded.

***

## Troubleshooting Common Issues

* **Opacity slider missing:** Confirm `show-opacity` is set on the component.
* **Alpha not captured:** Read `hexa` or `rgba` (not `hex`/`rgb`) from `event.detail` to keep the opacity value.
* **Value not updating:** Ensure your `change` handler writes the detail back to the bound `value` property and that `read-only`/`disabled` are not set.
* **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-gradient.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.