> 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/visual-picker.md).
# Visual Picker
`avonni-visual-picker`
Displays a set of richly-styled, selectable tiles for single or multiple selection.
## Overview
**Visual Picker** is a Lightning Web Component that displays a grid of selectable, card-style tiles—each with a title, description, avatar, tags, and fields—as a radio or checkbox group.
Use it in your own Lightning Web Components when users choose one or more options from a set of rich, image-forward tiles laid out in a responsive grid. You provide the items as data; the component manages selection, layout, ratios, and validation.
### Use Cases
* **Plan and pricing selection:** Present hosting or subscription tiers as tiles.
* **Template galleries:** Let users pick a layout, theme, or template.
* **Product choices:** Show selectable products with imagery and key specs.
* **Multi-select options:** Use the `checkbox` type for selecting several tiles.
* **Guided setup:** Offer visual options inside an onboarding or form step.
***
## Type Guidelines
| Type | Use Case |
| ---------- | -------------------------------------------------- |
| `radio` | Single, mutually exclusive choice (e.g. one plan). |
| `checkbox` | Multiple selections; bind `value` to an array. |
***
## Use Case Examples
### Example 1: Single hosting plan selection
**Scenario:** Let users pick one hosting plan from a grid of tiles that show price, projects, and storage, with two tiles visible initially.
```html
```
```js
// hostingPlanPicker.js
import { LightningElement } from 'lwc';
export default class HostingPlanPicker extends LightningElement {
value = 'growth';
fieldAttributes = { variant: 'label-inline', cols: 12 };
items = [
{
value: 'starter',
title: 'Starter',
description: 'For small teams getting started.',
avatar: { iconName: 'standard:product', variant: 'circle', size: 'large' },
tags: [{ label: 'Popular', variant: 'success' }],
fields: [
{ label: 'Price', value: '$9/mo' },
{ label: 'Storage', value: '5 GB' }
]
},
{
value: 'growth',
title: 'Growth',
description: 'For growing teams that need room to scale.',
avatar: { iconName: 'standard:opportunity', variant: 'circle', size: 'large' },
tags: [{ label: 'Best value', variant: 'brand' }],
fields: [
{ label: 'Price', value: '$29/mo' },
{ label: 'Storage', value: '100 GB' }
]
}
];
handleChange(event) {
this.value = event.detail.value; // selected item value
}
}
```
**Result:** A grid of 4-by-3 tiles with "Growth" selected; clicking another tile fires `change` with its value, and the show more button reveals additional plans.
### Example 2: Multi-select template gallery
**Scenario:** Allow users to select multiple templates from a tile grid.
```html
```
```js
// templateGallery.js
import { LightningElement } from 'lwc';
export default class TemplateGallery extends LightningElement {
value = ['blog'];
items = [
{ value: 'blog', title: 'Blog', description: 'Article layout.' },
{ value: 'shop', title: 'Shop', description: 'Storefront layout.' }
];
handleChange(event) {
this.value = event.detail.value; // array of selected values
}
}
```
**Result:** A grid of 16-by-9 tiles where users can select multiple templates; `change` fires with an array of selected values.
***
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----------------- | -------- |
| `collapsed-show-more-button` | The label for the show more button when the items are collapsed. | String | `"'Show more'"` | |
| `column-attributes` | Column attributes: cols, smallContainerCols, mediumContainerCols, largeContainerCols Number of columns depending on the width of the container. See 'cols' for accepted values. | AvonniColumnAttributes | — | |
| `disabled` | If present, the visual picker is disabled and the user cannot interact with it. | Boolean | `false` | |
| `expanded-show-more-button` | The label for the show more button when the items are expanded. | String | `"'Show less'"` | |
| `field-attributes` | Field attributes: variant, cols | AvonniFieldAttributes | — | |
| `hide-check-mark` | If present, hide the check mark when selected. | Boolean | `false` | |
| `image-attributes` | Image attributes: fallbackSrc, cropFit, position, size and height. | AvonniImageAttributes | — | |
| `is-loading` | If present, a spinner is shown to indicate that more items are loading. | Boolean | `false` | |
| `items` | Array of items with attributes populating the visual picker. | AvonniVisualPickerItem\[] | — | |
| `label` | Text label to title the visual picker. | String | — | |
| `loading-state-alternative-text` | Message displayed while the picker is in the loading state. | String | `"'Loading...'"` | |
| `max` | Maximum number of selected items. | Number | `Infinity` | |
| `max-count` | Maximum of items allowed in the visible list. This attribute is ignored if `enable-infinite-loading` is present. | Number | — | |
| `message-when-range-overflow` | Error message to be displayed when a range overflow is detected. | String | — | |
| `message-when-range-underflow` | Error message to be displayed when a range underflow is detected. | String | — | |
| `message-when-value-missing` | Error message to be displayed when the value is missing and input is required. | String | — | |
| `min` | Minimum number of selected options required. | Number | `0` | |
| `name` | The name of the visual picker. | String | — | Yes |
| `ratio` | The ratio of the items. Valid values include 1-by-1, 4-by-3, 16-by-9, 3-by-4 and 9-by-16. | String | `"1-by-1"` | |
| `required` | If present, at least one item must be selected. | Boolean | `false` | |
| `required-alternative-text` | The assistive text when the required attribute is set to true. | String | `"'Required'"` | |
| `size` | The size of the items. Valid values include xx-small (4rem x 4 rem), x-small (6rem x 6 rem), small (8rem x 8rem), medium (12rem x 12rem), large (15rem x 15rem), x-large (18rem x 18rem), xx-large (21rem x 21rem) and responsive. Only avatar appears when x-small and xx-small. | String | `"medium"` | |
| `type` | It defines the type of input. Valid values include radio and checkbox. | String | `"radio"` | |
| `validity` | Represents the validity states that an element can be in, with respect to constraint validation. | String | — | |
| `value` | Value of the selected item. For the checkbox type, the value can be an array. Ex: \[value1, value2], 'value1' or \['value1'] | (string | string\[]) | — |
| `variant` | Changes the appearance of the item when selected. Valid values include coverable and non-coverable. | String | `"non-coverable"` | |
### 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. | | | |
| `getErrorMessage` | Retrieve the current error message. If it is null than the input is valid. | | | |
| `reportValidity` | Displays the error messages and returns false if the input is invalid. If the input is valid, reportValidity() clears displayed error messages and returns true. | | | |
| `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 visual 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 value changed.
The `change` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ----------- |
| `value` | string | string\[] |
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 visual 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. |
#### `itemclick`
The event fired when an item is clicked.
The `itemclick` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ------------------- |
| `value` | string | Clicked item value. |
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. |
#### `itemsvisibilitytoggle`
The event fired when the show more/less button is clicked.
The `itemsvisibilitytoggle` event returns the following parameters.
| Parameter | Type | Description |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `show` | boolean | True if items are currently hidden and the click was meant to show more of them. False if the click was meant to hide the visible items. |
| `visibleItemsLength` | number | Length of the currently visible items. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | ---------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| 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. |
#### `loadmore`
The event fired when you scroll to the end of the visual picker. This event is fired only if `enable-infinite-loading` is true.
The `loadmore` 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-visual-picker-header-text-color` | color | `#3e3e3c` |
| `--avonni-visual-picker-header-font-size` | font | `0.75rem` |
| `--avonni-visual-picker-header-font-style` | font | `normal` |
| `--avonni-visual-picker-header-font-weight` | font | `400` |
| `--avonni-visual-picker-item-title-text-color` | color | `#080707` |
| `--avonni-visual-picker-item-title-font-size` | font | `1.25rem` |
| `--avonni-visual-picker-item-title-font-style` | font | `normal` |
| `--avonni-visual-picker-item-title-font-weight` | font | `700` |
| `--avonni-visual-picker-item-title-alignment` | alignment | `center` |
| `--avonni-visual-picker-item-description-text-color` | color | `#3e3e3c` |
| `--avonni-visual-picker-item-description-font-size` | font | `0.75rem` |
| `--avonni-visual-picker-item-description-font-style` | font | `normal` |
| `--avonni-visual-picker-item-description-font-weight` | font | `400` |
| `--avonni-visual-picker-item-description-line-clamp` | number | `2` |
| `--avonni-visual-picker-item-description-line-height` | dimension | `1.25` |
| `--avonni-visual-picker-item-description-alignment` | alignment | `center` |
| `--avonni-visual-picker-tags-alignment` | alignment | `center` |
| `--avonni-visual-picker-tags-padding` | padding | `0.5rem` |
| `--avonni-visual-picker-tag-alt-inverse-text-color` | color | — |
| `--avonni-visual-picker-tag-alt-inverse-color-background` | color | — |
| `--avonni-visual-picker-tag-alt-inverse-color-border` | color | — |
| `--avonni-visual-picker-tag-base-text-color` | color | — |
| `--avonni-visual-picker-tag-base-color-background` | color | — |
| `--avonni-visual-picker-tag-base-color-border` | color | — |
| `--avonni-visual-picker-tag-brand-text-color` | color | — |
| `--avonni-visual-picker-tag-brand-color-background` | color | — |
| `--avonni-visual-picker-tag-brand-color-border` | color | — |
| `--avonni-visual-picker-tag-error-text-color` | color | — |
| `--avonni-visual-picker-tag-error-color-background` | color | — |
| `--avonni-visual-picker-tag-error-color-border` | color | — |
| `--avonni-visual-picker-tag-info-text-color` | color | — |
| `--avonni-visual-picker-tag-info-color-background` | color | — |
| `--avonni-visual-picker-tag-info-color-border` | color | — |
| `--avonni-visual-picker-tag-inverse-text-color` | color | — |
| `--avonni-visual-picker-tag-inverse-color-background` | color | — |
| `--avonni-visual-picker-tag-inverse-color-border` | color | — |
| `--avonni-visual-picker-tag-offline-text-color` | color | — |
| `--avonni-visual-picker-tag-offline-color-background` | color | — |
| `--avonni-visual-picker-tag-offline-color-border` | color | — |
| `--avonni-visual-picker-tag-success-text-color` | color | — |
| `--avonni-visual-picker-tag-success-color-background` | color | — |
| `--avonni-visual-picker-tag-success-color-border` | color | — |
| `--avonni-visual-picker-tag-warning-text-color` | color | — |
| `--avonni-visual-picker-tag-warning-color-background` | color | — |
| `--avonni-visual-picker-tag-warning-color-border` | color | — |
| `--avonni-visual-picker-tag-label-font-size` | font | `0.75rem` |
| `--avonni-visual-picker-tag-label-font-style` | font | `normal` |
| `--avonni-visual-picker-tag-label-font-weight` | font | `700` |
| `--avonni-visual-picker-tag-radius-border` | sizing | `15rem` |
| `--avonni-visual-picker-tag-sizing-border` | dimension | `1px` |
| `--avonni-visual-picker-tag-styling-border` | styling | `solid` |
| `--avonni-visual-picker-tag-line-height` | dimension | `normal` |
| `--avonni-visual-picker-title-text-color` | color | `#080707` |
| `--avonni-visual-picker-title-text-color-selected` | color | `#181818` |
| `--avonni-visual-picker-title-font-size` | font | `1.25rem` |
| `--avonni-visual-picker-title-font-style` | font | `normal` |
| `--avonni-visual-picker-title-font-weight` | font | `700` |
| `--avonni-visual-picker-title-alignment` | alignment | `center` |
| `--avonni-visual-picker-title-padding` | padding | `0.15rem 0.75rem` |
| `--avonni-visual-picker-description-text-color` | color | `#3e3e3c` |
| `--avonni-visual-picker-description-font-size` | font | `0.75rem` |
| `--avonni-visual-picker-description-font-style` | font | `normal` |
| `--avonni-visual-picker-description-font-weight` | font | `400` |
| `--avonni-visual-picker-description-line-clamp` | number | `2` |
| `--avonni-visual-picker-description-line-height` | dimension | `1.25` |
| `--avonni-visual-picker-description-alignment` | alignment | `center` |
| `--avonni-visual-picker-color-background` | color | `#ffffff` |
| `--avonni-visual-picker-color-background-hover` | color | `#ffffff` |
| `--avonni-visual-picker-color-background-selected` | color | `#1b96ff` |
| `--avonni-visual-picker-color-border` | color | `#c9c9c9` |
| `--avonni-visual-picker-color-border-hover` | color | `#1b96ff` |
| `--avonni-visual-picker-color-border-selected` | color | `#1b96ff` |
| `--avonni-visual-picker-sizing-border` | sizing | `1px` |
| `--avonni-visual-picker-styling-border` | styling | `solid` |
| `--avonni-visual-picker-radius-border` | dimension | `0.25rem` |
| `--avonni-visual-picker-shadow` | shadow | `0 2px 2px rgb(0 0 0 / 5%)` |
| `--avonni-visual-picker-image-padding` | padding | `0rem` |
| `--avonni-visual-picker-responsive-sizing-max-height` | sizing | `21rem` |
| `--avonni-visual-picker-responsive-sizing-min-height` | sizing | `15rem` |
| `--avonni-visual-picker-overlay-background` | color | `linear-gradient(0deg, rgba(0, 0, 0, 0.7) 0%, rgba(0, 0, 0, 0.55) 75%, rgba(0, 0, 0, 0) 100%)` |
| `--avonni-visual-picker-overlay-fields-label-text-color` | color | `#fff` |
| `--avonni-visual-picker-overlay-fields-value-text-color` | color | `#fff` |
| `--avonni-visual-picker-overlay-text-color` | color | `#fff` |
| `--avonni-visual-picker-show-more-button-color-background` | color | — |
| `--avonni-visual-picker-show-more-button-color-background-active` | color | — |
| `--avonni-visual-picker-show-more-button-color-background-hover` | color | — |
| `--avonni-visual-picker-show-more-button-color-border` | color | — |
| `--avonni-visual-picker-show-more-button-color-border-active` | color | — |
| `--avonni-visual-picker-show-more-button-color-border-hover` | color | — |
| `--avonni-visual-picker-show-more-button-radius-border` | dimension | — |
| `--avonni-visual-picker-show-more-button-sizing-border` | sizing | — |
| `--avonni-visual-picker-show-more-button-spacing-block-end` | dimension | — |
| `--avonni-visual-picker-show-more-button-spacing-block-start` | dimension | — |
| `--avonni-visual-picker-show-more-button-spacing-inline-end` | dimension | — |
| `--avonni-visual-picker-show-more-button-spacing-inline-start` | dimension | — |
| `--avonni-visual-picker-show-more-button-text-color` | color | — |
| `--avonni-visual-picker-show-more-button-text-color-active` | color | — |
| `--avonni-visual-picker-show-more-button-text-color-hover` | color | — |
## Key Considerations
* **Required field:** `name` is required; bind `value` to component state to control selection.
* **Type and value:** For `checkbox`, `value` is an array; for `radio` it is a single string.
* **Layout:** Combine `size` and `ratio` for consistent tiles; small sizes (`xx-small`, `x-small`) show only the avatar.
* **Disabled items:** Set `disabled: true` on an item to prevent selecting it.
* **Validation:** Use `required` with `message-when-value-missing` for form steps.
* **Best Practice:** Set `name` and bind `value` to component state, and choose a `ratio`/`size` that suits your tile imagery so the grid stays consistent.
***
## Troubleshooting Common Issues
* **No selection persists:** Bind `value` to a tracked property and update it in the `change` handler.
* **Tiles look cramped:** Increase `size` or adjust `ratio` to fit your imagery and fields.
* **Checkbox value errors:** For `checkbox` type, ensure `value` is an array, not a string.
* **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/visual-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.