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

# Vertical Visual Picker

Let users pick from a vertical list of rich rows with avatars, images and optional sub-options, then use the choice later in the screen flow.

The Vertical Visual Picker stacks the choices as full-width rows, each with a title, a description and an avatar or image on the side. A support rep picks a plan and ticks its add-ons right under it, an agent picks a colleague from a list that shows who is online.

***

## Tutorials

Two step-by-step tutorials use this component. The [Visual Picker tutorials](https://docs.avonnicomponents.com/flow/tutorials/components/visual-picker.md) hub lists them with the Visual Picker ones.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Adding Sub-Items</strong></td><td>Group products under their category, with options users can tick inside each row.</td><td><a href="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FffowdYaksLeQnXsQ8zeC%2Fvisual-picker-cover-adding-sub-items.png?alt=media">visual-picker-cover-adding-sub-items.png</a></td><td><a href="https://docs.avonnicomponents.com/flow/tutorials/components/vertical-visual-picker/adding-sub-items.md">Adding sub-items</a></td></tr><tr><td><strong>Display a List of Online Contacts</strong></td><td>Show contacts as rows with their avatar and whether they are online.</td><td><a href="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FxO61FDWiod3oVp8yRUnm%2Fvisual-picker-cover-display-a-list-of-online-contacts.png?alt=media">visual-picker-cover-display-a-list-of-online-contacts.png</a></td><td><a href="https://docs.avonnicomponents.com/flow/tutorials/components/vertical-visual-picker/display-a-list-of-online-contacts.md">Display a list of online contacts</a></td></tr></tbody></table>

***

## Overview

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FAkVj8F5NID7kx33wV5Id%2Fvisual-picker-vertical-visual-picker-result.png?alt=media" alt="A Vertical Visual Picker listing Basic, Plus and Premier, with Plus selected and its Weekend coverage add-on ticked" width="320"><figcaption><p>Plus selected, with one of its add-ons ticked.</p></figcaption></figure>

It shares its data model with the [Visual Picker](https://docs.avonnicomponents.com/flow/flow-components/visual-picker.md): the same data sources, the same **Type**, the same pre-selection and the same outputs.

This page covers what is specific to the vertical list: longer text per row, the media on the left or the right, presence on avatars, and sub-items under a row. For a grid of cards, use the Visual Picker instead.

***

## Configuration

Click the component on the flow screen. The **Edit Vertical Visual Picker Component** panel opens on the right with three tabs: **Properties**, **Interactions** and **Style**. The sections below follow the **Properties** tab.

### Data Source

| Data Source                                                                                       | Use it when                                                                       |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [**Manual**](https://docs.avonnicomponents.com/flow/component-builder/data-sources/manual.md)     | The choices are fixed and you type them in the panel.                             |
| [**Variable**](https://docs.avonnicomponents.com/flow/component-builder/data-sources/variable.md) | A **Get Records** or an Assignment earlier in the flow already holds the records. |
| [**Picklist**](https://docs.avonnicomponents.com/flow/component-builder/data-sources/picklist.md) | The choices are the values of a picklist field.                                   |
| [**Query**](https://docs.avonnicomponents.com/flow/component-builder/data-sources/query.md)       | The component should fetch the records itself.                                    |

### Data Mapping

With **Variable** or **Query**, open **Data Mappings** and map **Value** to a field that is unique per record (the record Id is the safe choice), then **Title**, **Description** and **Image** or **Avatar** to the fields you want to show. Mapping works the same way as on the [Visual Picker](https://docs.avonnicomponents.com/flow/flow-components/visual-picker.md).

> **Example:** Query the Contacts of the current account, map **Title** to `Name`, **Description** to `Title` and the avatar **Image** to a photo URL field. The rep picks the contact to follow up with.

### Items

With **Manual**, each row is an entry of the **Items** list. A vertical row has fewer fields than a Visual Picker card (no tags, no hidden flag) and two of its own: **Media Position** and **Sub Items**.

| Item field                 | What it does                                                                                                                                             |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title**                  | The title of the row.                                                                                                                                    |
| **Value**                  | A unique value for the item. This is what the outputs return when the row is selected.                                                                   |
| **Description**            | Rich text displayed under the title.                                                                                                                     |
| **Image**                  | The image of the row. When an item has both an image and an avatar, the image is shown.                                                                  |
| **Image Alternative Text** | The text a screen reader announces for the image.                                                                                                        |
| **Media Position**         | Puts the avatar or the image on the **Left** *(default)* or the **Right** of the row.                                                                    |
| **Disabled**               | Grays out this row. The user cannot select it.                                                                                                           |
| **Avatar**                 | An avatar with **Variant** (Circle or Square, default Square), **Initials**, **Icon Name**, **Size**, **Image**, **Presence** and **Presence Position**. |
| **Sub Items**              | Extra options displayed in a box under the row, each with a **Label** and a **Value**.                                                                   |
| **Sub Items Multi Select** | Lets the user tick several sub-items instead of one.                                                                                                     |

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FrC8AYhLl6ZjklqQUEyrf%2Fvisual-picker-vertical-visual-picker-item-editor.png?alt=media" alt="The Plus item open in the Vertical Visual Picker panel on Media Position, Avatar, Sub Items and Sub Items Multi Select" width="375"><figcaption><p>Media Position, the avatar and the sub-items are set per item.</p></figcaption></figure>

#### Presence on avatars

**Presence** adds a status dot to the avatar: **Online**, **Busy**, **Focus**, **Offline**, **Blocked** or **Away**. **Presence Position** puts it at **Top Left**, **Top Right**, **Bottom Left** or **Bottom Right** *(default)*.

Map **Presence** to a field and the list shows each person's status. [Display a list of online contacts](https://docs.avonnicomponents.com/flow/tutorials/components/vertical-visual-picker/display-a-list-of-online-contacts.md) builds that list.

#### Sub-items

Sub-items let the user refine a choice without a second screen: pick the **Plus** plan, then tick the add-ons that go with it. They are always visible under their row, as radio buttons, or as checkboxes when **Sub Items Multi Select** is on.

{% stepper %}
{% step %}

#### Add the sub-items to a row

Open the item, then add one entry per option under **Sub Items**, each with a **Label** (`Weekend coverage`) and a **Value** (`Weekend`).
{% endstep %}

{% step %}

#### Choose one or several

Turn on **Sub Items Multi Select** to let the user tick several sub-items. Leave it off for one choice per row.
{% endstep %}

{% step %}

#### Read the picks after the screen

Ticking a sub-item marks its row as selected, but does not add the row's own value. **Value** and **Value Collection** hold the values of the selected rows and of the ticked sub-items: a user who selects the Plus row, then ticks Weekend coverage, returns `Plus;Weekend`. Clearing the row clears its sub-items.
{% endstep %}
{% endstepper %}

[Adding sub-items](https://docs.avonnicomponents.com/flow/tutorials/components/vertical-visual-picker/adding-sub-items.md) has a second example.

### Properties

**Label** is the text displayed above the list.

**Type** decides how many rows the user can select: **Radio** *(default)* for one, **Checkbox** for several. It works as on the [Visual Picker](https://docs.avonnicomponents.com/flow/flow-components/visual-picker.md).

**Value** pre-selects one row when **Type** is **Radio**. **Value Collection** pre-selects several when **Type** is **Checkbox**. With a **Variable** data source, the **Default Selection Collection** field under the collection pre-selects the rows whose records it contains.

**Size** sets the width of each row: **Small**, **Medium**, **Large** or **Responsive** *(default, full width)*.

**Variant** sets how a selected row looks: **Non Coverable** *(default)* adds a check mark, **Coverable** covers the whole row.

**Required** stops the user from moving to the next screen until they select a row.

**Hide Check Mark** hides the check mark on selected rows.

**Disabled** grays out the whole list. To disable one row, use the item's own **Disabled** field.

### Advanced Options

**Min** is the minimum number of rows the user must select, and **Max** the maximum. Both appear when **Type** is **Checkbox**. **Min** defaults to `0`. Only rows count toward them, sub-items do not. With **Max** set to `1`, selecting another row replaces the current one.

***

## Interactions

[Interactions](https://docs.avonnicomponents.com/flow/component-builder/interactions-panel.md) define what happens when users interact with the Vertical Visual Picker. Configure them from the **Interactions** tab of the Edit Vertical Visual Picker panel.

### Change

Fires when the user selects or clears a row or a sub-item. **Value**, **Value Collection**, **Selected Item** and **Selected Items** are updated before the interaction runs.

### Item Click

Fires when the user clicks a row, whether or not the selection changes. **Clicked Item** and **Clicked Item Value** carry the row that was clicked.

***

## Styling

The **Style** tab sets the look of the list and its rows.

{% tabs %}
{% tab title="Margin" %}
Controls the *outer* spacing around the picker.

* **Top / Right / Bottom / Left:** Adjust the space on each side.
  {% endtab %}

{% tab title="Padding" %}
Controls the *inner* spacing between the picker's content and its border.

* **Top / Right / Bottom / Left:** Adjust the inner spacing on each side.
  {% endtab %}

{% tab title="Size" %}
Controls the picker's dimensions.

* **Width / Height:** Set fixed dimensions.
* **Overflow:** Control how content that exceeds the bounds is handled.
* **Min Width / Max Width / Min Height / Max Height:** Constrain the size within bounds.
  {% endtab %}

{% tab title="Flow Dialog" %}
Adjusts display when opened as a modal dialog inside a Flow screen.

* **Width:** Dialog width.
* **Height:** Dialog height.
* **Background Color:** Dialog background color.
  {% endtab %}

{% tab title="Label" %}
Styles the item label text.

* **Color:** Set the label text color.
* **Font Size / Font Style / Font Weight:** Control the label typography.
  {% endtab %}

{% tab title="Title" %}
Styles the item title text.

* **Color:** Set the title text color.
* **Font Size / Font Style / Font Weight:** Control the title typography.
* **Alignment:** Align the title text.
  {% endtab %}

{% tab title="Description" %}
Styles the item description text.

* **Color:** Set the description text color.
* **Font Size / Font Style / Font Weight:** Control the description typography.
* **Alignment:** Align the description text.
  {% endtab %}

{% tab title="Background" %}
Sets the item background across states.

* **Background Color / Background Color Hover / Background Color Selected:** Set the background for the default, hover, and selected states.
* **Background Color Sub Items:** Set the background for sub-items.
  {% endtab %}

{% tab title="Border" %}
Customizes the item border across states.

* **Color / Color Hover / Color Selected:** Set the border color for the default, hover, and selected states.
* **Size / Style / Radius:** Control the border thickness, line style, and corner roundness.
* **Shadow:** Apply a box shadow.
  {% endtab %}

{% tab title="Show More Button" %}
Styles the "Show More" button that reveals additional items.

* **Background Color / Background Color Active / Background Color Hover:** Set the button background across states.
* **Text Color / Text Color Active / Text Color Hover:** Set the button text color across states.
* **Border Color / Border Color Active / Border Color Hover:** Set the button border color across states.
* **Border Size / Border Radius:** Control the border thickness and corner roundness.
* **Block Start / Block End / Inline Start / Inline End:** Control the spacing around the button.
  {% endtab %}
  {% endtabs %}

See the [Style Panel](https://docs.avonnicomponents.com/flow/component-builder/style-panel.md) for how style settings work.

***

## Output Variables

After the screen, select the screen element in Flow Builder, then the Vertical Visual Picker, and pick the output you need. The outputs match the [Visual Picker](https://docs.avonnicomponents.com/flow/flow-components/visual-picker.md) ones.

### Item Selection

Updated when the user selects or clears a row or a sub-item (the **Change** interaction).

| Output variable      | Type              | What it returns                                                                                                                                                              |
| -------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Value**            | Text              | The selected value. With **Checkbox** or sub-items, all selected values joined by semicolons, for example `Plus;Weekend`. A multi-select picklist field accepts this format. |
| **Value Collection** | Text Collection   | All selected values, rows and sub-items, one per element.                                                                                                                    |
| **Selected Item**    | Record            | The record behind the selected row, with a **Variable** or **Query** data source only. With **Checkbox**, the record of the first row in the selection.                      |
| **Selected Items**   | Record Collection | The records behind all selected rows, with a **Variable** or **Query** data source only.                                                                                     |

> **Example:** A rep picks a plan and its add-ons. An **Update Records** element writes **Value** into a multi-select picklist field on the Account, so the plan and its add-ons are saved in one field.

### Item Click

Updated when the user clicks a row (the **Item Click** interaction).

| Output variable        | Type   | What it returns                             |
| ---------------------- | ------ | ------------------------------------------- |
| **Clicked Item**       | Record | The record behind the row the user clicked. |
| **Clicked Item Value** | Text   | The value of the row the user clicked.      |

### Others

| Output variable     | Type    | What it returns                        |
| ------------------- | ------- | -------------------------------------- |
| **Number of Items** | Integer | The number of rows loaded in the list. |

### Flow Interaction Output Variables

Like all interactive Flow components, the Vertical Visual Picker exposes generic output slots (Variable 1 to 10) that an [Open Flow Dialog](https://docs.avonnicomponents.com/flow/component-builder/interactions-panel/open-flow-dialog.md) or [Open Flow Panel](https://docs.avonnicomponents.com/flow/component-builder/interactions-panel/open-flow-panel.md) interaction can fill with values from a launched flow. See [Flow Interaction Output Variables](https://docs.avonnicomponents.com/flow/component-builder/interactions-panel/flow-interaction-output-variables.md).

***

## Troubleshooting Common Issues

<details>

<summary>Value contains values I did not expect</summary>

Sub-item values are added to **Value** and **Value Collection** next to the row values. Give sub-items values that cannot be confused with row values, or split them after the screen with a formula or a loop.

</details>

<details>

<summary>The avatar is missing on a row</summary>

The item also has an **Image**. The image takes priority over the avatar. Clear **Image** to show the avatar.

</details>

<details>

<summary>Min or Max is not in the panel</summary>

Both appear only when **Type** is **Checkbox**, in the advanced part of the panel.

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avonnicomponents.com/flow/flow-components/vertical-visual-picker.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
