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.

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

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

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

// 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.
renderValue	Display the given color in the color gradient.	color	String	Color to display.

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.

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 [email protected] for assistance.