Image List

avonni-dd-image-list

The Avonni Data Driven Image List displays records in a image list format.

Overview

Image List is a data-driven Lightning Web Component that displays records as a responsive grid of image tiles, each with a label, description, optional image, and per-item actions.

The component runs in two modes. In query mode you set a query and a mapping object that maps record fields to each tile's label, name, description, and imageSrc using the {{Record.FieldApiName}} syntax. In static mode you provide tiles directly through the items property; the component ignores query and mapping and renders the items as-is. The grid is responsive, with separate column counts per breakpoint.

Use Cases

• Media galleries: Show files, images, or attachments as a browsable grid.
• Record cards: Present accounts, products, or contacts as image tiles with a label and description.
• Catalogs: Display products or destinations with imagery and quick actions.
• Curated lists: Render a static, in-memory set of featured items with images.
• Dashboards: Surface a searchable, filterable, paginated grid of records.

---

Use Case Examples

Example 1: Query mode

Scenario: Display Account records as a responsive image grid, with a per-record generated image, search, filters, pagination, and item actions.

<!-- accountGallery.html -->
<template>
    <avonni-dd-image-list
        actions={actions}
        allow-item-click
        cols="1"
        filters={accountFilters}
        header-caption="Query mode demo"
        header-show-items-count
        header-title="Accounts"
        image-attributes={imageAttributes}
        items-per-page="12"
        large-container-cols="2"
        mapping={accountMapping}
        medium-container-cols="2"
        no-results-message="No accounts found"
        pagination-attributes={paginationAttributes}
        query={accountQuery}
        search-fields={accountSearchFields}
        show-pagination
        small-container-cols="1"
        variant="base"
        onactionclick={handleActionClick}
        onitemclick={handleItemClick}
        onerror={handleError}
        onfilter={handleFilter}
    ></avonni-dd-image-list>
</template>

// accountGallery.js
import { LightningElement } from 'lwc';

export default class AccountGallery extends LightningElement {
    accountQuery = { objectApiName: 'Account', orderBy: 'Name ASC', limit: 50 };

    accountMapping = {
        label: '{{Record.Name}}',
        name: '{{Record.Id}}',
        description: '{{Record.Industry}}',
        imageSrc: 'https://api.dicebear.com/9.x/shapes/png?size=320&seed={{Record.Id}}'
    };

    accountSearchFields = ['Name'];
    accountFilters = ['Industry', 'BillingState'];
    actions = [
        { label: 'See more', name: 'seeMore', iconName: 'utility:preview' },
        { label: 'Delete', name: 'delete', iconName: 'utility:delete' }
    ];
    imageAttributes = { cropFit: 'cover', height: 200, position: 'top' };
    paginationAttributes = { align: 'center' };

    handleActionClick(event) {
        const { name, item, itemSObject } = event.detail; // itemSObject holds the record
    }
    handleItemClick(event) {
        const { item, itemSObject } = event.detail;
    }
    handleError(event) {
        const message = event.detail.message;
    }
    handleFilter(event) {
        const selections = event.detail.value;
    }
}

Result: A responsive grid of Account tiles (1–2 columns by breakpoint) with a generated image, the Industry as description, search, Industry/BillingState filters, pagination, and See more / Delete actions per tile.

Example 2: Static mode

Scenario: Render a curated, in-memory list of destinations with images and per-item actions, no SOQL required.

<!-- destinationGallery.html -->
<template>
    <avonni-dd-image-list
        actions={actions}
        allow-item-click
        cols="1"
        header-caption="Static mode demo"
        header-show-items-count
        header-title="Featured destinations"
        image-attributes={imageAttributes}
        items={items}
        items-per-page="4"
        large-container-cols="3"
        medium-container-cols="2"
        pagination-attributes={paginationAttributes}
        show-pagination
        small-container-cols="1"
        variant="base"
        onactionclick={handleActionClick}
        onitemclick={handleItemClick}
        onpagechange={handlePageChange}
    ></avonni-dd-image-list>
</template>

Result: A responsive grid of destination tiles (1–3 columns by breakpoint), four per page, each with its image, description, and See more / Delete actions. Because it is static mode, itemSObject is null and the tile data is in item.

---

Specifications

Attributes

Name	Description	Type	Default	Required
actions	Array of action objects. The actions are displayed on the right of every list item. On click on an action, the actionclick event is fired.	DdElementAction[]	—
allow-item-click	If true, the items are displayed as clickable, and a click on an item fires the itemclick event.	Boolean	false
alternative-text	Alternative text used to describe the image list. If the image list is sortable, it should describe its behavior, for example: "Sortable menu. Press spacebar to grab or drop an item. Press up and down arrow keys to change position. Press escape to cancel.	String	—
cols	Default number of list items columns. Valid values are 1, 2, 3, 4, 6 and 12.	integer	1
filters	Array of field API names that belong to the queried object. These fields will be displayed as user filters.	string[]	—
filters-attributes	Object defining the filters-specific attributes.	DdElementFiltersAttributes	—
header-actions	Array of actions to display at the top right of the header. On click on a header action, the headeractionclick event is fired.	DdElementAction[]	—
header-avatar	Avatar displayed at the top left of the header.	DdElementAvatar	—
header-caption	Header caption, displayed above the title.	String	—
header-help-text	If present, a help text icon is displayed next to the header title. On focus or hover on the icon, the header help text is displayed in a tooltip.	String	—
header-help-text-attributes	Object defining the help text-specific attributes.	DdElementHelpTextAttributes	—
header-show-items-count	If true, the number of items found is displayed in the header.	Boolean	false
header-title	Main title displayed in the header.	String	—
header-visible-actions-count	Number of header actions that appear as regular buttons. Remaining actions appear in a dropdown menu.	integer	—
image-attributes	Object defining the image layout.	DdImageListImageAttributes	—
items	Array of static items displayed in the image list. When this property is set, the image list ignores the query and mapping properties and displays the items directly.	DdImageListItem[]	—
items-per-page	If the pagination is enabled, number of items per page. Otherwise, number of items loaded at once.	integer	100
large-container-cols	Number of items columns when the list width is greater or equal to 1024px. Valid values are 1, 2, 3, 4, 6 and 12.	integer	—
mapping	Object defining the way the records returned by the query should be mapped to the list image item properties. To insert the value of a field, use the syntax {{Record.FieldApiName}}. For example, to use the value of the Name field, use {{Record.Name}}.	DdImageListMapping	—
medium-container-cols	Number of items columns when the list width is greater or equal to 768px. Valid values are 1, 2, 3, 4, 6 and 12.	integer	—
no-results-message	Message displayed when the query returns no results.	String	—
pagination-attributes	Object defining the pagination-specific attributes.	DdElementPaginationAttributes	—
query	Definition of the query to execute to get the records that will be mapped.	DdElementQuery	—
refresh-emp	Object describing a platform event that should be subscribed to in order to refresh the component when an event is published.	DdElementRefreshEmp	—
search-attributes	Object defining the search-specific attributes.	DdElementSearchAttributes	—
search-fields	Array of field API names that can be used by the search box to filter the records. The fields must belong to the queried object, and they must be filterable.	string[]	—
show-pagination	If true, a pagination is displayed at the bottom of the list. If false and the list has a height limit, the items will be loaded dynamically as the user scrolls. If false and the list does not have a height limit, a "show more" button will be displayed at the bottom of the list.	Boolean	false
side-panel-attributes	Object defining the side panel-specific attributes.	DdElementSidePanelAttributes	—
small-container-cols	Number of items columns when the list width is greater or equal to 480px. Valid values are 1, 2, 3, 4, 6 and 12.	integer	—
total-nb-items	Total number of records available in static mode. Set this property when you load the items yourself and want to load them progressively: the component then fires the loadmore event (when the pagination is disabled) or the pagechange event (when the pagination is enabled) so you can load the next records and update the items array. When left undefined, the provided items array is paginated on the client and these events are not fired. This property has no effect in query mode.	integer	—
variant	The variant changes the appearance of the image list. Valid values are base, quilted, woven and masonry.	String	"base"

Methods

Name	Description	Argument Name	Argument Type	Argument Description
refresh	Refresh the query and the records displayed in the component.	stayOnCurrentPage	Boolean	If true, the component will refresh but stay on the current page.

Mapping

In query mode, the mapping object maps queried record fields to each tile's properties. Insert a field value with the {{Record.FieldApiName}} syntax (for example, {{Record.Name}} for the Name field). You can also embed field values inside a larger string such as an image URL.

Mapping key	Description	Example
label	Tile label.	'{{Record.Name}}'
name	Unique tile name/identifier.	'{{Record.Id}}'
description	Tile description text.	'{{Record.Industry}}'
imageSrc	Image URL (field values can embed).	'/sfc/.../download/{{Record.LatestPublishedVersionId}}'

Custom Events

actionclick

Event fired when an item action is clicked.

The actionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.
item	object	Image list item the action belongs to, with the mapped label, name, description and imageSrc properties.
record	object	Record corresponding to the item the action belongs to. In static mode, no record is associated and this is null.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

error

The event fired when an error occurs in the component.

The error event returns the following parameters.

Parameter	Type	Description
message	string	Message of the error.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

filter

The event fired when the user filters the records.

The filter event returns the following parameters.

Parameter	Type	Description
value	object	Object containing the filters applied by the user. Its keys correspond to the field API names of the selected filters. The values are arrays of strings, corresponding to the values selected for the filter.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

headeractionclick

The event fired when a header action is clicked.

The headeractionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

itemclick

Event fired when an item is clicked.

The itemclick event returns the following parameters.

Parameter	Type	Description
item	object	Image list item that was clicked, with the mapped label, name, description and imageSrc properties.
record	object	Record corresponding to the item that was clicked. In static mode, no record is associated and this is null.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

loadmore

The event fired in static mode, when the user reaches the end of the component and more records remain to load (infinite loading). It is only fired when totalNbItems is set and the pagination is disabled. Load the next records and append them to the items array.

The loadmore event returns the following parameters.

Parameter	Type	Description
search	string	Current search value, when the search box is used. Apply it when loading the next records.
setIsLoading	function	Callback toggling the component loading state while the next records are loaded. Call setIsLoading(true) before loading the records and setIsLoading(false) once they are loaded.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

nbitemschange

The event fired when the number of items displayed in the component changes.

The nbitemschange event returns the following parameters.

Parameter	Type	Description
value	integer	Number of items displayed in the component.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

pagechange

The event fired in static mode, when the user navigates to another page or changes the search value. It is only fired when totalNbItems is set and the pagination is enabled. Load the records of the new page (applying the search) and replace the items array.

The pagechange event returns the following parameters.

Parameter	Type	Description
value	integer	New page number.
search	string	Current search value, when the search box is used. Apply it when loading the page records.
setIsLoading	function	Callback toggling the component loading state while the new page records are loaded. Call setIsLoading(true) before loading the records and setIsLoading(false) once they are loaded.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

actionclick

Event fired when an item action is clicked.

The actionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.
item	object	Image list item the action belongs to, with the mapped label, name, description and imageSrc properties.
itemSObject	object	Record corresponding to the item the action belongs to. In static mode, no record is associated and this is null.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

itemclick

Event fired when an item is clicked.

The itemclick event returns the following parameters.

Parameter	Type	Description
item	object	Image list item that was clicked, with the mapped label, name, description and imageSrc properties.
itemSObject	object	Record corresponding to the item that was clicked. In static mode, no record is associated and this is null.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

pagechange

The event fired when the page changes.

The pagechange event returns the following parameters.

Parameter	Type	Description
value	integer	New page number.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-dd-image-list-footer-color-background	color	—
--avonni-dd-image-list-footer-color-border	color	—
--avonni-dd-image-list-footer-radius-border	string	—
--avonni-dd-image-list-footer-sizing-border	string	—
--avonni-dd-image-list-footer-styling-border	string	—
--avonni-dd-image-list-header-actions-color-background	color	—
--avonni-dd-image-list-header-actions-color-background-active	color	—
--avonni-dd-image-list-header-actions-color-background-hover	color	—
--avonni-dd-image-list-header-actions-color-border	color	—
--avonni-dd-image-list-header-actions-color-border-active	color	—
--avonni-dd-image-list-header-actions-color-border-hover	color	—
--avonni-dd-image-list-header-actions-text-color	color	—
--avonni-dd-image-list-header-actions-text-color-active	color	—
--avonni-dd-image-list-header-actions-text-color-hover	color	—
--avonni-dd-image-list-header-caption-font-family	string	—
--avonni-dd-image-list-header-caption-font-size	dimension	—
--avonni-dd-image-list-header-caption-font-style	string	normal
--avonni-dd-image-list-header-caption-font-weight	number	400
--avonni-dd-image-list-header-caption-letter-spacing	string	—
--avonni-dd-image-list-header-caption-line-height	string	—
--avonni-dd-image-list-header-caption-text-color	color	#000000
--avonni-dd-image-list-header-color-background	color	—
--avonni-dd-image-list-header-color-border	color	—
--avonni-dd-image-list-header-color-border-bottom	color	#c9c9c9
--avonni-dd-image-list-header-icon-color-background	color	—
--avonni-dd-image-list-header-icon-color-foreground	color	—
--avonni-dd-image-list-header-icon-color-foreground-default	color	—
--avonni-dd-image-list-header-icon-radius-border	string	—
--avonni-dd-image-list-header-margin-block-end	dimension	—
--avonni-dd-image-list-header-radius-border	string	—
--avonni-dd-image-list-header-sizing-border	string	—
--avonni-dd-image-list-header-sizing-border-bottom	dimension	1px
--avonni-dd-image-list-header-spacing-block-end	dimension	0.75rem
--avonni-dd-image-list-header-spacing-block-start	dimension	0.75rem
--avonni-dd-image-list-header-spacing-inline-end	dimension	1rem
--avonni-dd-image-list-header-spacing-inline-start	dimension	1rem
--avonni-dd-image-list-header-styling-border	string	—
--avonni-dd-image-list-header-styling-border-bottom	string	solid
--avonni-dd-image-list-header-title-font-family	string	—
--avonni-dd-image-list-header-title-font-size	dimension	1rem
--avonni-dd-image-list-header-title-font-style	string	normal
--avonni-dd-image-list-header-title-font-weight	number	400
--avonni-dd-image-list-header-title-letter-spacing	string	—
--avonni-dd-image-list-header-title-line-height	number	1.25
--avonni-dd-image-list-header-title-text-color	color	#080707
--avonni-dd-image-list-item-cursor	string	pointer
--avonni-dd-image-list-pagination-active-button-color-background	color	#0176d3
--avonni-dd-image-list-pagination-active-button-color-background-active	color	#014486
--avonni-dd-image-list-pagination-active-button-color-background-hover	color	#014486
--avonni-dd-image-list-pagination-active-button-color-border	color	#0176d3
--avonni-dd-image-list-pagination-active-button-color-border-active	color	#014486
--avonni-dd-image-list-pagination-active-button-color-border-hover	color	#014486
--avonni-dd-image-list-pagination-active-button-text-color	color	#fff
--avonni-dd-image-list-pagination-active-button-text-color-active	color	#fff
--avonni-dd-image-list-pagination-active-button-text-color-hover	color	#fff
--avonni-dd-image-list-pagination-button-color-background	color	#fff
--avonni-dd-image-list-pagination-button-color-background-active	color	#f3f3f3
--avonni-dd-image-list-pagination-button-color-background-disabled	color	#fff
--avonni-dd-image-list-pagination-button-color-background-hover	color	#f3f3f3
--avonni-dd-image-list-pagination-button-color-border	color	#747474
--avonni-dd-image-list-pagination-button-color-border-active	color	#747474
--avonni-dd-image-list-pagination-button-color-border-disabled	color	#747474
--avonni-dd-image-list-pagination-button-color-border-hover	color	#747474
--avonni-dd-image-list-pagination-button-sizing-border	dimension	1px
--avonni-dd-image-list-pagination-button-styling-border	string	solid
--avonni-dd-image-list-pagination-button-text-color	color	#0176d3
--avonni-dd-image-list-pagination-button-text-color-active	color	#014486
--avonni-dd-image-list-pagination-button-text-color-disabled	color	#c9c9c9
--avonni-dd-image-list-pagination-button-text-color-hover	color	#014486
--avonni-dd-image-list-show-more-button-color-background	color	—
--avonni-dd-image-list-show-more-button-color-background-active	color	—
--avonni-dd-image-list-show-more-button-color-background-hover	color	—
--avonni-dd-image-list-show-more-button-color-border	color	—
--avonni-dd-image-list-show-more-button-color-border-active	color	—
--avonni-dd-image-list-show-more-button-color-border-hover	color	—
--avonni-dd-image-list-show-more-button-radius-border	string	—
--avonni-dd-image-list-show-more-button-sizing-border	string	—
--avonni-dd-image-list-show-more-button-spacing-block-end	dimension	—
--avonni-dd-image-list-show-more-button-spacing-block-start	dimension	—
--avonni-dd-image-list-show-more-button-spacing-inline-end	dimension	—
--avonni-dd-image-list-show-more-button-spacing-inline-start	dimension	—
--avonni-dd-image-list-show-more-button-text-color	color	—
--avonni-dd-image-list-show-more-button-text-color-active	color	—
--avonni-dd-image-list-show-more-button-text-color-hover	color	—

Key Considerations

• Mode is set by items: Setting items switches the list to static mode; query and mapping are then ignored.
• itemSObject in static mode: actionclick and itemclick carry the tile in item, but itemSObject is always null because there is no backing record.
• Responsive columns: cols is the default; small/medium/large-container-cols override it at 480px, 768px, and 1024px container widths.
• Image fit: Use image-attributes (cropFit, height, position, fallbackSrc) to control how tile images render and degrade.
• Clickability: itemclick only fires when allow-item-click is set.
• Best Practice: Set responsive column counts (small-container-cols, medium-container-cols, large-container-cols) so the grid adapts gracefully, and provide an image-attributes.fallbackSrc so tiles degrade well when an image fails to load.

---

Troubleshooting Common Issues

• Tiles show no image: Verify mapping.imageSrc (query mode) or imageSrc (static mode) resolves to a reachable URL; set image-attributes.fallbackSrc for graceful failures, and confirm external hosts are CSP Trusted Sites.
• Labels or descriptions are blank: Check the {{Record.FieldApiName}} tokens in mapping reference fields actually returned by the query.
• Item clicks do nothing: Ensure allow-item-click is set and onitemclick is wired in the template.
• If issues persist: Contact our support team at [email protected] for assistance.