Vertical Visual Picker

avonni-vertical-visual-picker

Displays a vertical list of selectable, richly-styled options for single or multiple selection.

Overview

Vertical Visual Picker is a Lightning Web Component that presents a vertical list of selectable, card-style options—each with a title, description, media, and tags—as a radio or checkbox group.

Use it in your own Lightning Web Components when users must choose one or more options from a set of rich, descriptive items stacked vertically. You supply the items as data; the component handles selection, validation, and an optional show more/less control.

Use Cases

• Plan selection: Let users pick a subscription or pricing plan.
• Onboarding choices: Present setup options with descriptive context.
• Settings: Offer mutually exclusive configuration choices.
• Multi-select lists: Use the checkbox type to select several options.
• Guided flows: Stack options vertically in a wizard 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 plan selection

Scenario: Let users pick one subscription plan from a vertical list, showing two plans initially with a show more button.

<!-- planPicker.html -->
<template>
    <avonni-vertical-visual-picker
        name="subscription-plan"
        label="Choose a subscription plan"
        items={items}
        value={value}
        type="radio"
        variant="non-coverable"
        size="responsive"
        max-count="2"
        collapsed-show-more-button="Show all plans"
        expanded-show-more-button="Show fewer plans"
        required
        onchange={handleChange}
    ></avonni-vertical-visual-picker>
</template>

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

export default class PlanPicker extends LightningElement {
    value = 'team';
    items = [
        {
            value: 'starter',
            title: 'Starter',
            description: 'For individuals getting started.',
            avatar: { iconName: 'standard:user', variant: 'circle', size: 'large' },
            tags: [{ label: 'Free', variant: 'success' }]
        },
        {
            value: 'team',
            title: 'Team',
            description: 'For small teams that collaborate.',
            avatar: { iconName: 'standard:groups', variant: 'circle', size: 'large' },
            tags: [{ label: 'Popular', variant: 'brand' }]
        }
    ];

    handleChange(event) {
        this.value = event.detail.value; // selected item value
    }
}

Result: A vertical list of plan cards with the "Team" plan selected; only two cards show until the user clicks "Show all plans".

Example 2: Multi-select with checkboxes

Scenario: Allow users to select multiple add-ons.

<!-- addOnPicker.html -->
<template>
    <avonni-vertical-visual-picker
        name="add-ons"
        label="Select add-ons"
        items={items}
        value={value}
        type="checkbox"
        min="1"
        required
        onchange={handleChange}
    ></avonni-vertical-visual-picker>
</template>

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

export default class AddOnPicker extends LightningElement {
    value = ['analytics'];
    items = [
        { value: 'analytics', title: 'Analytics', description: 'Advanced reporting.' },
        { value: 'sso', title: 'SSO', description: 'Single sign-on.' }
    ];

    handleChange(event) {
        this.value = event.detail.value; // array of selected values
    }
}

Result: A checkbox list where users can select several add-ons; 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'"
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'"
hide-check-mark	If present, hide the check mark when selected.	Boolean	false
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 vertical visual picker.	VerticalVisualPickerItem[]	—
label	Text label to title the vertical 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 vertical visual picker.	String	—	Yes
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	It defines the width of the item. Valid values include small, medium, large and responsive.	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	It 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 vertical 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 vertical 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 vertical 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 vertical 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-vertical-visual-picker-header-text-color	color	#3e3e3c
--avonni-vertical-visual-picker-header-font-size	font	0.75rem
--avonni-vertical-visual-picker-header-font-style	font	normal
--avonni-vertical-visual-picker-header-font-weight	font	400
--avonni-vertical-visual-picker-title-text-color	color	#080707
--avonni-vertical-visual-picker-title-font-size	font	1.25rem
--avonni-vertical-visual-picker-title-font-style	font	normal
--avonni-vertical-visual-picker-title-font-weight	font	400
--avonni-vertical-visual-picker-title-alignment	alignment	left
--avonni-vertical-visual-picker-description-text-color	color	#3e3e3c
--avonni-vertical-visual-picker-description-font-size	font	0.75rem
--avonni-vertical-visual-picker-description-font-style	font	normal
--avonni-vertical-visual-picker-description-font-weight	font	400
--avonni-vertical-visual-picker-description-alignment	alignment	left
--avonni-vertical-visual-picker-description-line-height	dimension	1.25
--avonni-vertical-visual-picker-figure-color-background	color	#ffffff
--avonni-vertical-visual-picker-figure-color-background-hover	color	#ffffff
--avonni-vertical-visual-picker-figure-color-background-selected	color	#1b96ff
--avonni-vertical-visual-picker-figure-color-border	color	#c9c9c9
--avonni-vertical-visual-picker-figure-color-border-hover	color	#1b96ff
--avonni-vertical-visual-picker-figure-color-border-selected	color	#1b96ff
--avonni-vertical-visual-picker-figure-sizing-border	sizing	1px
--avonni-vertical-visual-picker-figure-styling-border	styling	solid
--avonni-vertical-visual-picker-figure-radius-border	dimension	0.25rem
--avonni-vertical-visual-picker-figure-shadow-box	shadow	0 2px 2px rgb(0 0 0 / 5%)
--avonni-vertical-visual-picker-figure-tags-alignment	alignment	left
--avonni-vertical-visual-picker-sub-items-color-background	color	#f7f9fb
--avonni-vertical-visual-picker-show-more-button-spacing-block-end	dimension	0
--avonni-vertical-visual-picker-show-more-button-spacing-block-start	dimension	0
--avonni-vertical-visual-picker-show-more-button-spacing-inline-end	dimension	1rem
--avonni-vertical-visual-picker-show-more-button-spacing-inline-start	dimension	1rem
--avonni-vertical-visual-picker-show-more-button-color-background	color	#ffffff
--avonni-vertical-visual-picker-show-more-button-color-background-active	color	#f3f3f3
--avonni-vertical-visual-picker-show-more-button-color-background-hover	color	#f3f3f3
--avonni-vertical-visual-picker-show-more-button-color-border	color	#c9c9c9
--avonni-vertical-visual-picker-show-more-button-color-border-active	color	#c9c9c9
--avonni-vertical-visual-picker-show-more-button-color-border-hover	color	#c9c9c9
--avonni-vertical-visual-picker-show-more-button-text-color	color	#0176d3
--avonni-vertical-visual-picker-show-more-button-text-color-active	color	#014486
--avonni-vertical-visual-picker-show-more-button-text-color-hover	color	#014486
--avonni-vertical-visual-picker-show-more-button-radius-border	dimension	0.25rem
--avonni-vertical-visual-picker-show-more-button-sizing-border	sizing	1px
--avonni-vertical-visual-picker-help-message-height	dimension	0px
--avonni-vertical-visual-picker-legend-height	dimension	0px

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.
• Disabled items: Set disabled: true on an individual item to prevent its selection.
• Show more: max-count limits visible items and reveals the show more button; it is ignored when infinite loading is enabled.
• Validation: Use required, min, and max with the message-when attributes to enforce selection rules.
• Best Practice: Set name and bind value to component state so selection persists, and use required with message-when-value-missing for form steps.

---

Troubleshooting Common Issues

• No selection persists: Bind value to a tracked property and update it in the change handler.
• Show more button missing: Confirm max-count is less than the number of items.
• 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.