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

# Visual Picker

## Overview

<figure><img src="/files/KqXfhaajWlyK8kVRxyak" alt="" width="375"><figcaption></figcaption></figure>

The Visual Picker lets users choose one or multiple options from a grid of selectable cards. Use it when options benefit from images, avatars, or rich descriptions — for example, selecting a product, a workflow template, or an account type.

***

## Configuration

To configure it, click the component on the Flow screen. The **Edit Visual Picker Component** panel opens on the right with three tabs: Properties, Interactions, and Style. The sections below mirror the Properties tab.

### Data Source

The **Data Source** setting determines where picker items come from.

| Data Source                                                      | Best For                              | When to Use                                                 |
| ---------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------- |
| [**Manual**](/flow/component-builder/data-sources/manual.md)     | Fixed, pre-defined options            | Static choices that never change                            |
| [**Variable**](/flow/component-builder/data-sources/variable.md) | Items from a Flow collection variable | Options driven by prior flow steps                          |
| [**Picklist**](/flow/component-builder/data-sources/picklist.md) | A Salesforce picklist field's values  | Presenting a predefined set of options for selection        |
| [**Query**](/flow/component-builder/data-sources/query.md)       | Live Salesforce records               | Dynamic options fetched without a separate Get Records step |

{% hint style="info" %}
Images cannot be added to picklist value items.
{% endhint %}

### Data Mapping

When using Variable, Picklist, or Query, configure **Data Mappings** to tell the component which Salesforce fields map to which parts of each item — for example, mapping "Account Name" to the Title attribute.

<figure><img src="/files/TU8gJVpiCvwM2EN6aIsQ" alt=""><figcaption></figcaption></figure>

### Properties

**Label** sets the label displayed above the picker.

**Type** defines the selection behavior.

| Type                  | What it does                                             |
| --------------------- | -------------------------------------------------------- |
| **Radio** *(default)* | Single selection — only one item can be chosen at a time |
| **Checkbox**          | Multiple selection — users can pick more than one item   |

**Value** pre-selects an item when Type is **Radio**. Enter the value of the item to pre-select.

**Value Collection** pre-selects multiple items when Type is **Checkbox**.

**Size** controls the size of each picker item. Options: XX-Small, X-Small, Small, Medium *(default)*, Large, X-Large, XX-Large, Responsive.

**Ratio** sets the aspect ratio applied to each item when Size is not Responsive. Options: 1-by-1 *(default)*, 4-by-3, 16-by-9, 3-by-4, 9-by-16. Requires a non-responsive **Size**.

**Variant** controls the appearance of items when selected.

| Variant                       | What it looks like                                                 |
| ----------------------------- | ------------------------------------------------------------------ |
| **Non Coverable** *(default)* | A checkmark appears in the upper-right corner of the selected item |
| **Coverable**                 | The entire item is covered/highlighted when selected               |

<figure><img src="/files/5bo7fcGt5HBck4RqgcuY" alt="" width="201"><figcaption><p>Non coverable vs Coverable variant</p></figcaption></figure>

**Required** prevents users from proceeding to the next screen without making a selection.

**Hide Check Mark** hides the check mark indicator when an item is selected.

**Disabled** grays out the picker and prevents user selection.

### Item Layout

Controls the positioning of content inside each picker card.

* **Title Position** — where the title appears within the figure (Top, Bottom, Center *(default)*).
* **Description Position** — where the description appears (Top, Bottom, Center *(default)*).
* **Avatar Position** — where the avatar appears relative to the content (Top, Bottom, Left to the title *(default)*, Right to the title, Left to the content, Right to the content).

### Image

Controls how images appear inside picker items.

* **Image Fallback** — a fallback image shown when an item's image is missing or invalid.
* **Position** — where the image sits relative to the content (Left, Right, Top *(default)*, Bottom, Background, Overlay).
* **Size** — controls image width (for left/right positions) or height (for other positions): Small, Medium, Large *(default)*.
* **Height** — overrides the size with a specific pixel height. Applies to Top, Bottom, Background, and Overlay positions.
* **Crop Fit** — how the image fills its container: Cover *(default)*, Contain, Fill, None.

### Fields Layout

Controls how internal fields are displayed within each picker item — set the number of columns and the field label variant.

### Layout

Responsive grid configuration when **Size** is set to **Responsive**. Set column counts for each container breakpoint (Default, Small, Medium, Large).

### Advanced Options

**Min** sets the minimum number of items that must be selected. Only applies when **Type** is **Checkbox**. Defaults to 0.

**Max** sets the maximum number of items that can be selected. Only applies when **Type** is **Checkbox**.

> **Selection Range:** By setting Min and Max together you can precisely manage the number of options a user can select.

<figure><img src="/files/nb9GWUSU1iq92247nGa0" alt=""><figcaption></figcaption></figure>

**Name** sets the name attribute of the visual picker input. Useful when multiple Visual Pickers are present on the same screen.

## Interactions

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

### Change

Fires when the user selects or deselects an item. Use this to store the selection in a flow variable or drive conditional logic — the output variables `value`, `valueCollection`, `selectedItem`, and `selectedItems` are updated before the interaction runs.

### Item Click

Fires when the user clicks an item, regardless of whether the selection state changes. Use this to preview details or trigger side effects on click — the output variables `clickedItem` and `clickedItemValue` are updated before the interaction runs.

***

## Styling

The **Style** tab lets you customize the look and feel of the Visual Picker. Configure it from the **Style** tab of the Edit panel.

{% 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="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.
  {% endtab %}

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

* **Size / Radius / Style:** Control the border thickness, corner roundness, and line style.
* **Color / Color Hover / Color Selected:** Set the border color for the default, hover, and selected states.
* **Shadow:** Apply a box shadow.
  {% 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="Figure Title" %}
Styles the figure title text.

* **Color / Selected Color:** Set the title color for the default and selected states.
* **Font Size / Font Style / Font Weight:** Control the title typography.
* **Line Clamp:** Limit the title to a maximum number of lines.
  {% endtab %}

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

* **Color / Selected Color:** Set the description color for the default and selected states.
* **Font Size / Font Style / Font Weight:** Control the description typography.
* **Line Clamp:** Limit the description to a maximum number of lines.
  {% 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.
  {% 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.
* **Line Clamp:** Limit the description to a maximum number of lines.
  {% endtab %}

{% tab title="Responsive Sizing" %}
Constrains the item height responsively.

* **Min Height / Max Height:** Set the responsive height bounds.
  {% endtab %}

{% tab title="Avatar" %}
Controls avatar placement.

* **Vertical Alignment:** Align avatars within the picker (top, center, bottom).
  {% endtab %}

{% tab title="Tag" %}
Styles the tag typography and shape.

* **Font Size / Font Style / Font Weight:** Control the tag typography.
* **Border Size / Border Style / Border Radius:** Control the tag border thickness, line style, and corner roundness.
* **Line Height:** Set the tag line height.
  {% endtab %}

{% tab title="Tag Colors" %}
Sets the tag colors. **Background**, **Border Color**, and **Text Color** are set per variant (Alt Inverse, Base, Brand, Error, Info, Inverse, Offline, Success, Warning).

* **Background:** Set the tag background color.
* **Border Color:** Set the tag border color.
* **Text Color:** Set the tag text color.
  {% endtab %}
  {% endtabs %}

***

## Examples

<figure><img src="/files/1U8aNOa7ySim7Su1zxr4" alt=""><figcaption></figcaption></figure>

{% @arcade/embed url="<https://app.arcade.software/share/4oqeIsfSNhKS7GlT4liv>" flowId="4oqeIsfSNhKS7GlT4liv" %}

***

## Output Variables

The Visual Picker exposes these output variables you can reference in your flow after the screen. To use them, select the screen element in Flow Builder, then the Visual Picker component, and pick the output variable you need.

<figure><img src="/files/U7ygJzgCwdRfjqVCfr17" alt=""><figcaption><p>Example of displaying the accessed value on a text element.</p></figcaption></figure>

### Item Selection

Updated when the user selects or deselects an item (fires with the **Change** interaction).

| Output variable      | Type              | What it returns                                                                                                                |
| -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Selected Item**    | Record (SObject)  | The full record behind the last selected item. Use this when you need field values from the selected record.                   |
| **Selected Items**   | Record Collection | All currently selected records. Use this for checkbox (multi-select) pickers when you need the full records.                   |
| **Value Collection** | Text Collection   | The values of all currently selected items. Use this for checkbox pickers when you only need the values, not the full records. |

> **Which output should I use?** For Radio (single selection), use **Selected Item** for the full record. For Checkbox (multiple selection), use **Value Collection** for the values or **Selected Items** for the full records. To pass selected values to an Apex action, use the `valueCollectionSerialized` input property (a JSON string, e.g. `["Banking","Biotechnology"]`) — set it via a **Set Flow Variable** interaction on **Change**.

### Item Click

Updated when the user clicks an item (fires with the **Item Click** interaction).

| Output variable        | Type             | What it returns                                   |
| ---------------------- | ---------------- | ------------------------------------------------- |
| **Clicked Item**       | Record (SObject) | The full record behind the item the user clicked. |
| **Clicked Item Value** | Text (String)    | The value of the item the user clicked.           |

> **Example:** After a Visual Picker screen listing product tiers, add a **Display Text** element that references `{!Visual_Picker.clickedItemValue}` to show the value of the last card the user clicked.

### Others

| Output variable     | Type    | What it returns                                           |
| ------------------- | ------- | --------------------------------------------------------- |
| **Number of Items** | Integer | The total number of items currently loaded in the picker. |

### Flow Interaction Output Variables

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


---

# 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/flow/flow-components/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.