Icon Picker

avonni-icon-picker

Lets users browse and select a Lightning Design System icon.

Overview

Icon Picker is a Lightning Web Component that lets users browse and select a Lightning Design System icon from a searchable, categorized dropdown.

Use it in your own Lightning Web Components whenever a user needs to choose an icon—configuring a custom record, a navigation item, or a theme. You control the label, placeholder, button appearance, hidden categories, and validation through attributes, and read the chosen icon from the change event or the value attribute.

Use Cases

• Configuration screens: Let admins pick an icon for a custom item or tab.
• Theme builders: Choose icons for buttons, links, or navigation.
• Form inputs: Add an icon field to a custom record-edit form.
• Metadata editors: Assign an SLDS icon to a category or status.
• Personalization: Allow users to pick an avatar or shortcut icon.

---

Variant Guidelines

Variant	Use Case
standard	Label above the field (default).
label-inline	Label horizontally aligned with the field.
label-hidden	Label hidden visually but read by screen readers.
label-stacked	Label stacked above a stacked form field.

---

Use Case Examples

Example 1: Required icon field on a form

Scenario: Add a required icon picker to a custom configuration form and read the chosen icon on change.

<!-- iconField.html -->
<template>
    <avonni-icon-picker
        label="Choose an icon"
        placeholder="Select an icon"
        field-level-help="Browse and select a Lightning Design System icon."
        value={value}
        required
        search-input-placeholder="Type icon name to search"
        onchange={handleChange}
    ></avonni-icon-picker>
</template>

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

export default class IconField extends LightningElement {
    value = 'standard:account';

    handleChange(event) {
        this.value = event.detail.value; // e.g. 'standard:contact' or '' when cleared
    }
}

Result: A required icon picker showing the account icon; choosing a new icon fires change with the selected value.

Example 2: Compact picker with hidden categories

Scenario: Show a bordered, label-hidden picker that excludes the Doctype and Action categories.

<!-- compactIconPicker.html -->
<template>
    <avonni-icon-picker
        label="Icon"
        variant="label-hidden"
        menu-variant="border"
        menu-icon-size="small"
        hidden-categories={hiddenCategories}
        onchange={handleChange}
    ></avonni-icon-picker>
</template>

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

export default class CompactIconPicker extends LightningElement {
    hiddenCategories = ['Doctype', 'Action'];

    handleChange(event) {
        const selected = event.detail.value;
    }
}

Result: A compact bordered picker with the label available only to assistive technology and a focused category list.

---

Specifications

Attributes

Name	Description	Type	Default	Required
access-key	Specifies a shortcut key to activate or focus an element.	String	—
cancel-button-label	Text label for the cancel button.	String	"'Cancel'"
clear-button-alternative-text	Alternative text for the clear button.	String	"'Clear'"
disabled	If present, the input field is disabled and users cannot interact with it.	Boolean	false
done-button-label	Text label for the done button.	String	"'Done'"
field-level-help	Help text detailing the purpose and function of the input.	String	—
hidden-categories	The icon categories that will be hidden by default.	string[]	—
hide-clear-icon	If present, it is not possible to clear a selected option using the input clear icon.	Boolean	false
hide-footer	If present, the dropdown footer is hidden.	Boolean	false
hide-input-text	If present, the input text next to the icon button is hidden.	Boolean	false
label	Text label for the input.	String	—
menu-icon-size	The size of the icon. Options include xx-small, x-small, small, medium, or large.	String	"medium"
menu-label	Optional text to be shown on the button.	String	—
menu-variant	The variant changes the look of the button. Accepted variants include bare, container, border, border-filled, bare-inverse, and border-inverse. This value defaults to border.	String	"border"
message-when-bad-input	Error message to be displayed when a bad input is detected.	String	—
name	Specifies the name of an input element.	String	—
placeholder	Text that is displayed when the field is empty, to prompt the user for a valid entry.	String	—
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'"
search-input-placeholder	Text that is displayed in the search input when the input is empty.	String	—
value	The Lightning Design System name of the selected icon. Names are written in the format 'standard:account' where 'standard' is the category, and 'account' is the specific icon to be displayed.	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	Remove focus from the input element.
focus	Sets focus on the input element.

Custom Events

blur

The event fired when the focus is removed from the icon picker.

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

The change event returns the following parameters.

Parameter	Type	Description
value	string	Value of the selected icon.

The event properties are as follows.

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.

focus

The event fired when the focus is set on the icon 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.

blur

The event fired when the focus is removed from the icon picker.

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

The change event returns the following parameters.

Parameter	Type	Description
value	string	Value of the selected icon.

The event properties are as follows.

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.

focus

The event fired when the focus is set on the icon 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-icon-picker-label-text-color	color	#444444
--avonni-icon-picker-label-font-size	font	0.75rem
--avonni-icon-picker-label-font-style	font	normal
--avonni-icon-picker-label-font-weight	font	400
--avonni-builder-icon-picker-popover-height	dimension	14rem

Key Considerations

• Value format: value is the SLDS category:name string (e.g. standard:account).
• Validation: With required, call reportValidity() to display errors and customize the message via message-when-bad-input.
• Clearing: Set hide-clear-icon to prevent users from clearing the value; otherwise the clear icon emits a change with an empty value.
• Categories: Use hidden-categories to remove categories you don't support.
• Best Practice: Provide a label and field-level-help for clarity, and hide categories you don't need with hidden-categories to keep the picker focused.

---

Troubleshooting Common Issues

• Selected icon not displaying: Confirm value is a valid SLDS name in category:name format.
• Change not firing: Ensure the onchange handler is wired and read event.detail.value.
• Validation not showing: Set required and call reportValidity() from your form's submit handler.
• If issues persist: Contact our support team at [email protected] for assistance.