> 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/dynamic-components/components/visual-picker.md). # Visual Picker The Avonni Visual Picker displays choices as selectable cards or tiles, giving users a visually engaging way to pick one or more options instead of a plain dropdown or list. ## 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). ## Configuration To configure the Visual Picker, select it on the canvas. The **Edit Visual Picker** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab. ### Data Source Before building your Visual Picker, tell the component where to get the options it should display. You have several options, depending on the source and nature of your data:
ManualEnter data directly into the component configuration.
VariableThis is useful for data that changes based on user interactions or other component logic.
QueryThis is the most common option for displaying Salesforce records.
PicklistRetrieve data dynamically from a standard or custom picklist field within Salesforce./pages/NMTcHeq9UuKYUmBedI8t
### Data Mapping When using a dynamic data source (Variable, Query, or Picklist), configure the **Data Mappings** section to tell the component how to build each tile from your data. Map fields from your data source to the following item properties: * **Value** — the unique identifier stored when the user selects an item. * **Figure Title** — the title displayed inside the figure area of the tile. * **Figure Description** — rich text displayed under the figure title. * **Title** — secondary title displayed below the figure area. * **Description** — rich text displayed under the item title. * **Image Source** — URL of the tile image (takes priority over avatar when both are set). * **Image Alternative Text** — accessibility text for the image. * **Avatar** — avatar configuration shown when no image is provided. * **Tags** — badge tags displayed on the tile. * **Fields** — additional key/value fields rendered in the item content area. ### Content #### Label The **Label** setting defines the text title shown above the Visual Picker. Use it to describe the choice being offered to the user (for example, "Select a Category"). #### Type The **Type** setting determines whether the user can select one option or multiple options: * **Radio** (default) — allows only a single selection, like radio buttons. * **Checkbox** — allows multiple selections, like checkboxes. #### Value The **Value** setting holds the currently selected item's value. Bind this to a Text Variable resource so the selected value is available elsewhere in your Dynamic Component. Requires: **Type** = **Radio**. #### Value Collection The **Value Collection** setting holds the currently selected items' values as a list. Bind this to a collection Variable resource. Requires: **Type** = **Checkbox**. #### Size The **Size** setting controls the dimensions of each tile. Options: **Xx-Small**, **X-Small**, **Small**, **Medium**, **Large**, **X-Large**, **Xx-Large**, and **Responsive**. When set to **Responsive**, the tile dimensions adapt to the container width using the **Layout** (column attributes) settings. #### Ratio The **Ratio** setting controls the aspect ratio of each tile (when **Size** is not **Responsive**). Options: **1-by-1** (square, default), **4-by-3**, **16-by-9**, **3-by-4**, **9-by-16**. Requires: **Size** ≠ **Responsive**. #### Variant The **Variant** setting changes how a tile looks when selected: * **Non Coverable** (default) — a subtle indicator (outline or checkmark) is shown on selected tiles. * **Coverable** — a more prominent fill or overlay is shown on selected tiles. #### Required If **Required** is enabled, the user must select at least one option before the form can be submitted. #### Hide Check Mark If **Hide Check Mark** is enabled, the checkmark indicator is not shown on selected tiles. #### Disabled If **Disabled** is enabled, the Visual Picker is read-only and the user cannot interact with it. #### Min The minimum number of options the user must select. Requires: **Type** = **Checkbox**. #### Max The maximum number of options the user can select. Requires: **Type** = **Checkbox**. ### Layout The **Layout** panel controls the position of content elements within each tile. These settings apply to all items. * **Title Position** — controls where the figure title appears inside the tile: **Top**, **Bottom**, or **Center** (default). * **Description Position** — controls where the figure description appears: **Top**, **Bottom**, or **Center** (default). * **Avatar Position** — controls where the avatar is placed relative to the tile content: **Top**, **Bottom**, **Left to the title** (default), **Right to the title**, **Left to the content**, or **Right to the content**. ### Image The **Image** panel controls how item images are displayed across all tiles. * **Image Fallback** — the image shown when a tile's image URL is invalid or missing. * **Position** — where the image appears relative to the tile content: **Left**, **Right**, **Top** (default), **Bottom**, **Background**, or **Overlay**. * **Size** — controls the image width (for Left/Right positions) or height (for other positions): **Small**, **Medium**, or **Large** (default). * **Height** — overrides the image height in pixels. Only applies when **Position** is **Top**, **Bottom**, **Background**, or **Overlay**. Requires: **Position** = **Top**, **Bottom**, **Background**, or **Overlay**. * **Crop Fit** — how the image fits inside its container: **Cover** (default), **Contain**, **Fill**, or **None**. ### Fields Layout The **Fields Layout** panel controls the appearance of the key/value fields displayed within each tile. * **Number of Columns** — the number of columns per row in the smallest container (also acts as the fallback for all sizes). Options: 1 (default), 2, 3, 4, 6, or 12. * **Variant** — controls how field labels are displayed: **Standard** (label above the value, default), **Label Hidden**, **Label Inline**, or **Label Stacked**. ### Responsive Layout When **Size** is set to **Responsive**, this additional **Layout** panel appears and lets you configure the number of columns each tile occupies at different container widths. * **Number of Columns** — columns in the smallest container (below 480 px); also the fallback for larger sizes. * **Number of Columns Small Container** — columns in a small container (above 480 px). * **Number of Columns Medium Container** — columns in a medium container (above 768 px). * **Number of Columns Large Container** — columns in a large container (above 1024 px). ### Set Component Visibility All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md). ## Interactions [Interactions](/dynamic-components/component-builder/interactions.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 every time the user's selection changes — whether adding or removing a selection. Use this to filter other components, set Variable values, execute flows, or navigate to other pages based on the current selection. ### Item Click Fires when a user clicks a tile, regardless of whether the selection state changes. Use the **clickedItem** output to access the clicked tile's data and drive navigation, record updates, or any flow logic tied to the specific tile. ## Output Variables The Visual Picker exposes these output variables you can reference elsewhere on the page after the user interacts with it. ### Item Click When a user clicks a tile, these variables update with the clicked tile's data. | Output variable | Type | What it returns | | ------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Clicked Item** | Object | The full data object of the tile the user clicked — includes its value, title, description, image, avatar, tags, and fields. | | **Clicked Item sObject** | Record (SObject) | The Salesforce record associated with the clicked tile. Requires a **Query** or **Variable** data source. | > **Example:** When a user clicks a product tile, use **Clicked Item** to display the product's details in a panel beside the picker, or use **Clicked Item sObject** to pre-populate a record-edit form with the underlying record. ### Item Selection When a user selects or deselects a tile, these variables update with the current selection state. | Output variable | Type | What it returns | | -------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | **Selected Item** | Object | The last item selected by the user — includes its value, title, description, image, avatar, tags, and fields. | | **Selected Items** | Object | All currently selected items as a collection. Useful when **Type** is **Checkbox** and multiple tiles can be active at once. | | **Selected Item sObject** | Record (SObject) | The Salesforce record associated with the last selected item. Requires a **Query** or **Variable** data source. | | **Selected Items sObject** | Record Collection (SObject\[]) | The Salesforce records for all selected items. Requires a **Query** or **Variable** data source. | > **Example:** After a user selects a pricing plan tile, use **Selected Item** to drive a summary panel, or pass **Selected Items sObject** to a flow to process all chosen records at once. ### Others | Output variable | Type | What it returns | | ------------------- | ------ | ---------------------------------------------------------------- | | **Number of Items** | Number | The total number of tiles currently loaded in the Visual Picker. | --- # 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/dynamic-components/components/visual-picker.md?ask=&goal= ``` `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.