# Image List ## Overview The Image List component renders images from either manual entries or Salesforce queries in four distinct layout styles: base grid, quilted, woven, or masonry. Users can browse, search, and filter images while optional item actions let them interact with individual items. Configure everything through the Properties Panel—from responsive column counts to fallback images for missing sources. ### Use Cases * **Displaying product image galleries** on Product record pages, where sales reps need to see all available photos. * **Building team directory pages** with employee photos that link to their user profiles. * **Creating portfolio showcases on Experience Sites** for partners or customers to browse project examples. * **Showing property photos on real estate listing** records for agents reviewing available inventory. * **Presenting event photo collections** from marketing campaigns with filtering by event type or date. * **Displaying asset libraries** where users can search and filter images by category, name, or custom attributes. *** ## Quick Start: Display Contact Photos on an Account Page Build a working image gallery showing all Contacts associated with the current Account. This uses standard Salesforce objects so that you can follow along in any org.
Prerequisites: Your Contacts need photos. If they don't have PhotoUrl populated, you can use the standard user icon as a fallback, or upload pictures to a few test Contacts first. {% stepper %} {% step %} #### Create a New Component in Dynamic Components * Open the **Avonni Dynamic Components** app from the App Launcher * Click **New Component** * Give your component a name (e.g., "Contact Photo Gallery") * Set [**Target Page Object**](https://docs.avonnicomponents.com/dynamic-components/core-concepts/target-page-object) to **Account** — this tells the component it will operate on Account record pages and gives you access to the `$Component` variable for referencing the current record fields. {% endstep %} {% step %} #### Add the Image List Element * In the component canvas, click **Add Element** or drag from the Elements panel * Select **Image List** from the available elements * The Image List appears on your canvas, ready for configuration in the Properties Panel {% endstep %} {% step %} #### **Configure the Data Source** In the Properties Panel on the right: * Set **Data Source** to **Query** * Click **Create Query** * For **Object**, select **Contact** * Under **Filters**, add: [`AccountId = '$Component.RecordId'`](#user-content-fn-1)[^1] * For **Order By**, select **LastName** with direction **Ascending** * Click **Done** to save the query
{% endstep %} {% step %} #### **Map Your Fields** In the **Data Mappings** section: * **Label**: Select `Name` (this shows the Contact's full name under each photo) * **Description**: Select `Title` (shows their job title) * **Image Source**: Select `PhotoUrl` (the standard Contact photo field) {% hint style="info" %} #### Note Label and Description are optional. Only Image Source is required to display the gallery. Use Label and Description when you want to show additional context alongside each image—leave them empty for a cleaner, image-only display. {% endhint %}
{% endstep %} {% step %} #### Configure the Header In the **Header** section: * **Title**: Enter `Team Contacts` * **Caption**: Enter `People associated with this account` * **Is Joined**: Toggle **On** — this visually connects the header to the gallery body
{% endstep %} {% step %} #### **Configure the Layout** In the **Content** section: * **Variant**: Select `Masonry` for a clean grid layout **Other layout options:** * **Quilted** — Alternates between larger featured images and smaller ones, creating visual hierarchy * **Woven** — Interlocking pattern that weaves images in alternating rows for a balanced look * **Base** —
In the **Layout** section: * **Number of Columns**: `4` * **Number of Columns (Small Container)**: `2` * **Number of Columns (Medium Container)**: `3` * **Number of Columns (Large Container)**: `4`
{% endstep %} {% step %} #### **Set a Fallback Image** In the **Image** section: * **Image Fallback**: Enter a URL to a placeholder image, or use an SLDS icon reference. This ensures Contacts without photos still display cleanly. {% endstep %} {% step %} #### Add Click Interaction Make contact photos clickable to navigate to the Contact record: * Click the **Interactions** tab in the Properties Panel * Under **Item Click**, click **Add Item Click** * In the interaction dialog, configure: * **Type**: Select `Navigate` * **Page Reference Type**: Select `Record Page` * **Object API Name**: Select `Contact` * **Record Id**: Select `Record: Id` (the ID of the clicked Contact) * **Action Name**: Enter `View` * **Open Console Tab**: Leave toggled Off * Click **Save** Now when users click any contact photo, they navigate directly to that Contact's record page {% endstep %} {% step %} #### **Save and Activate** * Click **Save** * Click **Activation** and assign the page to your org, app, or record type * Navigate to any Account record with Contacts to see your gallery {% endstep %} {% endstepper %} *** ## Configuration Settings ### Data Source The Data Source setting determines where your images come from. Choose Manual to define images directly in the component configuration, or Query to pull images dynamically from Salesforce records | Setting | Description | Example | | -------- | ----------------------------------------------------- | ------- | | **Mode** | Manual (static content) or Query (Salesforce records) | Query | **Manual Mode Items** When using Manual mode, you define each image directly in the component configuration. This works well for static galleries where images don't change frequently, such as a fixed set of product icons, team banners, or instructional graphics. | Setting | Description | Example | | --------------- | ------------------------------------------- | ---------------------------------- | | **Label** | Display name for the image | "Product Front View" | | **Description** | Additional detail text shown with the image | "High-resolution photo showing..." | | **Image** | URL to the image file | /resource/products/widget.png | | **Name** | Internal identifier for the item | product-front-01 | **Query Mode Data Mappings** When using Query mode, you connect Salesforce fields to the image list display. Each mapping tells the component which field contains the data for that element—like which field holds the image URL or the display label. | Setting | Description | Example | | ----------------- | ----------------------------- | ------------------------------ | | **Label** | Field containing display name | Name, Title\_\_c | | **Description** | Field containing detail text | Description\_\_c, Caption\_\_c | | **Image Source** | Field containing image URL | PhotoUrl\_\_c, ImageURL\_\_c | | **Filters** | Field for filter values | Category\_\_c, Type\_\_c | | **Search Fields** | Fields to search against | Name, Description\_\_c | *** ### Content These settings control the overall appearance and behavior of the image list, including which layout variant to use and how users interact with items. | Setting | Description | Example | | ------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Variant** | Layout style for the images | Base, Quilted, Woven, Masonry | | **Show Number of Items** | Display total count of images | true / false | | **Items Clickable** | Allow users to click/tap images |

true / false
NOTE: make sure to configure the interaction to make this functional

| **Layout Variants Explained:** * **Base** — A clean, uniform grid where all images display at the same size. Best for consistent content like headshots or product thumbnails. * **Quilted** — A structured layout that alternates between larger featured images and smaller supporting images. Creates a visual hierarchy while maintaining an organized feel. * **Woven** — An interlocking pattern that weaves images together in alternating rows. Adds visual interest while keeping a balanced, symmetrical appearance. * **Masonry** — A Pinterest-style staggered layout where images maintain their natural aspect ratios. Ideal for varied content like portfolio work, lifestyle photos, or user-generated images *** ### Header Add a header area above your image list with a title, caption, avatar, and action buttons. Use this to label your gallery and provide quick actions, such as uploading new images or changing view options. | Setting | Description | Example | | ---------------------------- | --------------------------------------- | --------------------------------- | | **Title** | Main header text | "Product Gallery" | | **Caption** | Secondary text below title | "Click any image to view details" | | **Avatar Image** | URL to header avatar/logo | /resource/logo.png | | **Is Joined** | Visual style connecting header to body | true / false | | **Actions** | Button actions in header area | Add Action → Label: "Upload" | | **Visibile Actions Buttons** | Number of actions shown before overflow | 2 | | **Hide Actions** | Hide all header actions | true / false | | **Disable Actions** | Gray out header actions | true / false | *** ### Layout Control how many columns display at different screen sizes. Setting different values for small, medium, and large containers ensures your gallery looks good on mobile, tablet, and desktop. | Setting | Description | Example | | ---------------------------------------- | ------------------------- | ------- | | **Number of Columns** | Default column count | 4 | | **Number of Columns (Small Container)** | Columns on small screens | 1 | | **Number of Columns (Medium Container)** | Columns on medium screens | 2 | | **Number of Columns (Large Container)** | Columns on large screens | 4 | *** ### Image Configure how individual images are rendered in the gallery. Set a fallback for missing images, control image positioning, and define how images crop to fit their containers. | Setting | Description | Example | | ------------------- | ---------------------------------------------------- | ------------------------- | | **Image Fallback** | URL to display when image source is invalid or empty | /resource/placeholder.png | | **Position** | Where the image appears in the item | Top, Bottom, Left, Right | | **Crop Fit** | How images scale within their container | Cover, Contain, Fill | | **Crop Position X** | Horizontal alignment of cropped images | Left, Center, Right | | **Crop Position Y** | Vertical alignment of cropped images | Top, Center, Bottom | *** ### Actions .Add actions that appear on individual image items, such as viewing details, downloading, or editing. Each action can trigger a different interaction when clicked Configure each item action with a label, icon, and interaction to trigger when clicked. *** ### Pagination For galleries with many images, pagination breaks the collection into pages to improve load times and make browsing easier. Users navigate between pages using the pagination controls. | Setting | Description | Example | | ---------------------------- | ------------------------------ | ------------ | | **Show Pagination** | Display pagination controls | true / false | | **Number of Items Per Page** | Images shown before pagination | 12 | *** ### Filter Let users narrow down the gallery by filtering on mapped field values. Choose where the filter controls appear based on your page layout and the prominence you want for filtering. | Setting | Description | Example | | -------- | ---------------------------- | -------------------------- | | **Type** | Where filter controls appear | Horizontal, Panel, Popover | *** ### Search Enable a search input that lets users find images by typing keywords. The search matches against the fields you specified in the Search Fields data mapping. *** ### Side Panel Configure an optional side panel for filters, details, or additional content. The panel can appear on either side and can start collapsed to save space. | Setting | Description | Example | | ---------------------- | --------------------------------- | ------------ | | **Position** | Which side the panel appears | Left, Right | | **Is Closed** | Panel starts collapsed | true / false | | **Hide Toggle Button** | Remove the expand/collapse button | true / false | | **Reset Button Label** | Text for filter reset action | "Clear All" | ### No Result Message Customize the message users see when no images match their search or filter criteria. A helpful message guides users to adjust their filters or try different search terms. *** ## Interactions Define what happens when users interact with images in your gallery. [**The Interactions tab**](https://docs.avonnicomponents.com/dynamic-components/component-builder/interactions) lets you configure responses to clicks and actions without writing code. ### **Available Triggers** | Trigger | Description | Use Case | | ----------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | **Item Click** | Fires when a user clicks on an image (requires Items Clickable to be On) | Navigate to a detail page, open a larger preview, or show related information | | **Item Action Click** | Fires when a user clicks an action button on an image item | Download the image, edit details, or delete the record | | **Header Action Click** | Fires when a user clicks an action button in the header | Upload new images, change view settings, or export the gallery | ### **Configuring Interactions** 1. Select the Image List element on your canvas 2. Click the **Interactions** tab in the Properties Panel 3. Choose a trigger (Item Click, Item Action Click, or Header Action Click) 4. Click **Add Action** and select your interaction type 5. Configure the action settings and save ### **Common Interaction Patterns** #### **Navigate to Record on Click** Let users click an image to view the full record: 1. Set **Items Clickable** to On in Content settings 2. In Interactions, select **Item Click** 3. Add Action → **Navigate** 4. Set Target to **Record Page** 5. Map the Record ID to your image record's ID field #### **Open Full-Size Preview in Panel** Display a larger version of the image in a side panel: 1. Set **Items Clickable** to On in Content settings 2. In Interactions, select **Item Click** 3. Add Action → **Open Dynamic Component Panel** 4. Select a Dynamic Component configured to display the full image 5. Pass the Image Source URL as an input variable *** ## Example: Build a Product Photo Gallery This tutorial walks you through creating a Pinterest-style photo gallery that displays on Product record pages. Users will be able to browse product images, filter by category, and click photos to take action. #### What You'll Build A masonry-layout gallery displaying all photos associated with the current Product. The gallery includes horizontal category filters, pagination for extensive collections, and clickable images.
#### Where It Will Appear Once you build and deploy this component, it appears on **Product record pages** in Lightning Experience. When a user opens any Product record, they see the photo gallery showing all images linked to that specific Product. The component automatically filters to show only photos belonging to the Product they're viewing ### Prerequisites This example assumes you have a custom object to store product photos. If you don't have one, create a custom object called **Product Photo** (API name: `Product_Photo__c`) with these fields | Field Label | API Name | Type | | -------------- | -------------- | --------------------------------------------------------- | | **Photo Name** | Name | Text (standard) | | **Product** | ProductId\_\_c | Lookup (to Product2) | | **Photo URL** | PhotoURL\_\_c | URL | | **Caption** | Caption\_\_c | Text | | **Category** | Category\_\_c | Picklist (e.g., Front View, Side View, Detail, Lifestyle) | | **Sort Order** | SortOrder\_\_c | Number | *** {% stepper %} {% step %} #### Create a New Component in Dynamic Components * Open the **Avonni Experiences** app from the App Launcher * Click on Get Started on the Dynamic Components card * Click **New Component** * Give your component a name (e.g., "Product Photo Gallery") * Set **Target Page Object** to **Product** — this tells the component it will operate on Product record pages and gives you access to the `$Component` variable for referencing the current record fields {% endstep %} {% step %} #### Add the Image List Element * Select **Image List** from the available elements * The Image List appears on your canvas, ready for configuration in the Properties Panel {% endstep %} {% step %} #### Configure the Data Source With the Image List element selected, configure the query in the Properties Panel: * Set **Data Source** to **Query** * Click **Create Query** * **Object**: Select `Product_Photo` (the custom object you created in Prerequisites) * **Filters**: Add `ProductId__c = '{{$Component.recordId}}'` — this filters the photos only to show records where the Product lookup matches the Product record the user is currently viewing * **Order By**: Select `SortOrder__c` with direction **Ascending** * Click **Done**
{% endstep %} {% step %} #### Map Your Fields In the **Data Mappings** section, connect your Salesforce fields to the gallery display: * **Label**: Select `Photo Name` — displays the photo name below each image * **Description**: Select `Caption__c` — shows additional context for the photo * **Image Source**: Select `PhotoURL__c` — the actual image to display * **Filters**: Select `Category__c` — enables filtering by this picklist {% endstep %} {% step %} #### Configure the Header In the **Header** section: * **Title**: Enter `Product Photos` * **Caption**: Enter `Browse images by category` * **Is Joined**: Toggle **On** — visually connects the header to the gallery body {% endstep %} {% step %} #### Configure the Gallery Appearance In the **Content** section: * **Variant**: Select `Masonry` — creates a Pinterest-style staggered layout * **Items Clickable**: Toggle **On** — allows users to interact with images {% endstep %} {% step %} #### Set Up Responsive Columns In the **Layout** section, configure how many columns display at different screen sizes: * **Number of Columns (Small Container)**: `1` — single column on mobile * **Number of Columns (Medium Container)**: `2` — two columns on tablets * **Number of Columns (Large Container)**: `3` — three columns on desktop {% endstep %} {% step %} #### Enable Pagination In the **Pagination** section: * **Show Pagination**: Toggle **On** * **Number of Items Per Page**: Enter `9` — shows 9 photos before pagination controls appear {% endstep %} {% step %} #### Configure Filters In the **Filter** section: * **Type**: Select `Horizontal` — displays category filters as a horizontal bar above the gallery {% endstep %} {% step %} #### Add Click Interaction Now when users click any photo in the gallery, they navigate directly to that Product Photo record page * Click the **Interactions** tab in the Properties Panel * Under **Item Click**, click **Add Item Click** * In the interaction dialog, configure: * **Type**: Select `Navigate` * **Page Reference Type**: Select `Record Page` * **Object API Name**: Select `Product Photo` * **Record Id**: Select `Record: Id` (the ID of the clicked image record) * **Action Name**: Enter `View` * **Open Console Tab**: Leave toggled Off * Click **Save** {% endstep %} {% step %} #### Save and Test * Click **Save** in Lightning App Builder * Click **Activation** and assign the page to your org or specific apps * Navigate to a Product record that has associated photos {% endstep %} {% endstepper %} #### What You Should See Your gallery displays product photos in a masonry layout, with images of varying heights elegantly arranged. Above the gallery, horizontal filter buttons let users filter by category (Front View, Side View, etc.). Pagination controls appear at the bottom when there are more than 9 photos. [^1]: $Component component is accessible from the mapped values.