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.

<!-- hostingPlanPicker.html -->
<template>
    <avonni-visual-picker
        name="hosting-plan"
        label="Choose a hosting plan"
        items={items}
        value={value}
        type="radio"
        variant="non-coverable"
        size="large"
        ratio="4-by-3"
        max-count="2"
        collapsed-show-more-button="Show all plans"
        expanded-show-more-button="Show fewer plans"
        required
        message-when-value-missing="Please select a plan to continue."
        field-attributes={fieldAttributes}
        onchange={handleChange}
    ></avonni-visual-picker>
</template>

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

<!-- templateGallery.html -->
<template>
    <avonni-visual-picker
        name="templates"
        label="Select templates"
        items={items}
        value={value}
        type="checkbox"
        ratio="16-by-9"
        size="medium"
        onchange={handleChange}
    ></avonni-visual-picker>
</template>

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

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