> 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/icon-picker.md).
# 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.
```html
```
```js
// 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.
```html
```
```js
// 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. |
### 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 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/icon-picker.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.