# Visual Picker

## Overview

The Visual Picker is ideal for scenarios where visual representation of the options enhances the user experience. Key features include:

* **Visual Options**: Display options with images, icons, and text, making them more engaging than plain text lists.
* **Single or Multiple Selection**: Configure the component to allow users to select either a single option (like radio buttons) or multiple options (like checkboxes).
* **Customizable Layout**: Control the appearance and arrangement of the options (e.g., aspect ratio, styling).
* **Data-Driven**: Populate the options from various data sources (Manual, Variable, Query, Picklist).
* **Reactive**: The selected value(s) are stored in a Variable resource, making them available for use in other parts of your Dynamic Component (filters, formulas, interactions).

## Configuring the Visual Picker

Select the Visual Picker component on the canvas to access its properties in the Properties Panel (right panel).

### Basic Properties

These properties control the fundamental data and labeling of the Visual Picker.

* **API Name**: (Text) A unique identifier for this component instance (e.g., ProductCategoryPicker, PriorityPicker).
* **Label**: (Text) The text label displayed above or next to the Visual Picker. Example: "Select a Category:", "Choose your Interests:".
* **Field Level Help**: (Text, Optional) Help text displayed next to the label.
* **Value**: (Text or Collection - Crucially Important) This property holds the value(s) of the currently selected item(s).
  * **Single Selection** (Radio Type): Bind this to a Text Variable resource. The variable will hold the value of the selected item.
  * **Multiple Selection** (Checkbox Type): Bind this to a Collection Variable resource (of type Text, typically). The variable will hold a list of the value properties of the selected items.
* Placeholder: Placeholder is displayed when no option is selected.

### Data Source Configuration

* **Data Source**: Choose how the Visual Picker's options are populated:
  * Manual: You manually enter the options (label, value, image/icon, etc.) directly in the component's properties. Suitable for small, static sets of options.
  * Variable: Use a Variable resource (typically a collection variable) to define the options. This allows for more dynamic options.
  * Query: Use an Avonni Query Data Source to retrieve options from a Salesforce object.
  * Picklist: Use an Avonni Picklist Data Source to populate options from a Salesforce picklist field.
* **Items/Options**: The available settings in this section depends on the Data Source.
  * Manual Data Source: If you selected "Manual" as your Data Source: Add options. You can add values like: label, value, image or icon.
  * Data Mappings (for Variable, Query, and Picklist Data Sources): If you choose a Variable, Query or Picklist data source:
    * **Label**: Map the field from your data source that contains the text to display for each option (e.g., Name for an Account, ProductName for a Product).
    * **Value**: Map the field containing each option's unique identifier (e.g., Id for a Salesforce record). This will be stored in the Value property when the user selects.
    * **Description**: (Optional) Map a field to display additional text below the label.
    * **Image Source/Icon**: (Optional) Map a field to display an image or icon for each option.

### Behavior and Appearance

* **Type**: (Text - Select from options) Determines whether the user can select one option or multiple options:
  * Radio: Allows only single selection (like radio buttons).
  * Checkbox: Allows multiple selections (like checkboxes).
* **Selection Range** (Checkbox Type Only): If Type is checkbox, you can set:
  * Min: The minimum number of options the user must select.
  * Max: The maximum number of options the user can select.
* **Ratio**: (Text - Select from options) Controls the visual items' aspect ratio (shape). Examples: 1:1 (square), 2:3 (taller rectangle), 16:9 (widescreen). This affects how images/icons are displayed.
* **Variant**: (Text - Select from options) Controls the visual style of the selected item(s):
  * Non-coverable: A subtle visual indicator (e.g., an outline or checkmark) is shown for selected items.
  * Coverable: A more prominent visual indicator (e.g., a background color fill) is shown for selected items.

### General Component Properties

* **Disabled**: (Boolean - Checkbox) If enabled, the Visual Picker is disabled, and the user cannot interact with it.
* **Read Only**: (Boolean - Checkbox) If enabled, the user can see the options, but they cannot change the selection.
* **Required**: (Boolean - Checkbox) If enabled, the user must select one option.

## Interactions

* **On Change**: This is the primary interaction for the Visual Picker. It triggers every time the user's selection changes (adds or removes a selection).
  * Use Cases:
    * Update other components based on the selection (e.g., filter a Data Table).
    * Set Variable values.
    * Execute Flows.
    * Navigate to other pages.
  * Accessing Selected Values:
    * !VisualPickerName.value: return a single value or a list of values.

## Key Considerations

* **Data Source Choice**: Choose the Data Source (Manual, Variable, Query, Picklist) that best suits your needs. For dynamic data, use Query or Picklist.
* **Interactions**: Consider using an On Change interaction.

## In Summary

The Visual Picker component is a flexible and interactive component to select options