> 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/vertical-visual-picker.md).

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

```html
<!-- 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>
```

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

```html
<!-- 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>
```

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

#### `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 <support@avonni.app> 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/vertical-visual-picker.md?ask=<question>&goal=<endgoal>
```

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