List
avonni-dd-list
The Avonni Data Driven List displays records in a list format.
Overview
List is a data-driven Lightning Web Component that displays Salesforce records, or a set of static items, as a configurable vertical or horizontal list.
The List supports two modes. In query mode, you provide a query and a mapping that turns each returned record into a list item. In static mode, you provide an items array directly; when items is set, the component ignores query and mapping and renders the items as-is. Both modes share the same layout, action, avatar, and pagination options.
Use Cases
Record lists: Show accounts, contacts, or any object as a clean list.
Related records: Display child or related records next to a parent.
Navigation menus: Render static items as a clickable menu.
Selection lists: Use the check-list variant to let end users select items.
Dashboards: Combine multiple lists in columns for a compact overview.
Galleries: Use media attributes to show images alongside list items.
Use Case Examples
Example 1: Query mode
Scenario: Display accounts as a paginated list with avatars, filters, search, and clickable items.
Result: A paginated list of accounts, each with a circular avatar, name, industry, and a See more / Delete action menu. Searching and filtering refine the query; clicking an item fires itemclick with the record.
Example 2: Static mode
Scenario: Show a fixed set of featured destinations supplied directly as items, with no query.
Result: A paginated list of static items, each with an avatar, label, and description. Because there is no query, itemSObject is null in the itemclick and actionclick events—use the item property instead.
Specifications
Attributes
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 list items are displayed as clickable, and a click on an item fires the itemclick event.
Boolean
false
avatar-attributes
Object defining how the items avatars are displayed. This is the default attributes applied to all the items. They can be overridden for specific items by their mapping.
DdListAvatarAttributes
—
cols
Default number of list items columns. Valid values are 1, 2, 3, 4, 6 and 12.
integer
1
divider
Divider used to separate the list items. Valid values are none, top, bottom and around.
String
"none"
fields
Array of field API names that belong to the queried object. The fields are used to display more details on the list items. The mapping label and description should be used for the primary information.
string[]
—
fields-attributes
Object defining the fields layout.
DdListFieldsAttributes
—
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-metric-aggregation-fields
Array of aggregation query definitions, used to display metrics in the header.
DdElementHeaderMetricAggregationField[]
—
header-show-items-count
If true, the number of items found is displayed in the header.
Boolean
false
header-show-sort
If true, the sort field and direction are displayed in the header. The sort is based on the value of the orderBy query parameter.
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
—
hide-no-results-image
If true, the image displayed when the query returns no results is hidden.
Boolean
false
hide-no-results-message
If true, the message displayed when the query returns no results is hidden.
Boolean
false
items
Array of static items displayed in the list. When this property is set, the list ignores the query and mapping properties and displays the items directly.
DdListItem[]
—
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 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}}.
DdListMapping
—
media-actions
Array of action objects displayed on top of the items media. On click on a media action, the mediaactionclick event is fired.
DdElementAction[]
—
media-attributes
Object defining how items media are displayed.
DdListMediaAttributes
—
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[]
—
selected-items-names
Used by the check-list variant. Array of selected items key field values. These represent the unique key names of items that are currently selected in the list. Updated automatically when items are checked or unchecked.
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
—
sortable
If true, it is possible to reorder the list items. Only the base variant supports item sorting. Not supported when the items are displayed in multiple columns.
Boolean
false
sortable-icon-name
Lightning Design System name of the sortable icon. Names are written in the format 'standard:account' where 'standard' is the category, and 'account' is the specific icon to be displayed. The icon appears next to sortable items to indicate they can be dragged.
String
—
sortable-icon-position
Position of the sortable icon relative to the list item content. Valid values are left and right.
String
"right"
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
Variant of the list. Valid values are base, single-line, or check-list. The base variant displays the items as a vertical list. The single-line variant displays items horizontally. The check-list variant displays a vertical list of items with checkboxes.
String
"base"
variant-attributes
Object defining variant-specific attributes.
DdListVariantAttributes
—
visible-actions-count
Number of item actions that appear as regular buttons. Remaining actions appear in a dropdown menu.
integer
"1 if there is only one action, 0 if there are multiple actions"
visible-media-actions-count
Number of media actions that appear as regular buttons. Remaining actions appear in a dropdown menu.
integer
"1 if there is only one media action, 0 if there are multiple media actions"
Mapping
In query mode, the mapping object converts each queried record into a list item. Insert a field value with the {{Record.FieldApiName}} syntax. The most useful mapping keys are:
name— unique key of the item, usually{{Record.Id}}.label— the primary item text, e.g.{{Record.Name}}.description— secondary text under the label.avatar— an avatar object, e.g.{ fallbackIconName: 'standard:account' }.
In static mode, supply the same shape directly in the items array (no {{Record.*}} placeholders—use literal values).
Methods
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.
Custom Events
actionclick
Event fired when an item action is clicked.
The actionclick event returns the following parameters.
name
string
Name of the action clicked.
item
object
List item the action belongs to, with its mapped 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.
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.
message
string
Message of the error.
The event properties are as follows.
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.
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.
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.
name
string
Name of the action clicked.
The event properties are as follows.
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.
item
object
List item that was clicked, with its mapped 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.
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.
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.
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.
mediaactionclick
Event fired when an item media action is clicked.
The mediaactionclick event returns the following parameters.
name
string
Name of the media action clicked.
item
object
List item the media action belongs to, with its mapped properties.
record
object
Record corresponding to the item the media action belongs to. In static mode, no record is associated and this is null.
The event properties are as follows.
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.
value
integer
Number of items displayed in the component.
The event properties are as follows.
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.
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.
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.
reorder
Event fired when the list items are reordered by the user.
The reorder event returns the following parameters.
names
string[]
Array of item names, corresponding to the new order.
The event properties are as follows.
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.
select
Event fired when the item selection is updated. If items are checked by default, this event will be fired when the query is first executed. It is also fired when items are checked or unchecked by the user.
The select event returns the following parameters.
item
object
List item that was checked or unchecked, with its mapped properties.
record
object
Record corresponding to the item that was checked or unchecked. In static mode, no record is associated and this is null.
selected
boolean
True if the item was checked, false if it was unchecked.
selectedItemsNames
string[]
Array of item key names, corresponding to the current selection.
The event properties are as follows.
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.
message
string
Message of the error.
The event properties are as follows.
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.
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.
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.
name
string
Name of the action clicked.
The event properties are as follows.
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.
value
integer
Number of items displayed in the component.
The event properties are as follows.
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
--avonni-dd-list-footer-color-background
color
—
--avonni-dd-list-footer-color-border
color
—
--avonni-dd-list-footer-radius-border
string
—
--avonni-dd-list-footer-sizing-border
string
—
--avonni-dd-list-footer-styling-border
string
—
--avonni-dd-list-header-actions-color-background
color
—
--avonni-dd-list-header-actions-color-background-active
color
—
--avonni-dd-list-header-actions-color-background-hover
color
—
--avonni-dd-list-header-actions-color-border
color
—
--avonni-dd-list-header-actions-color-border-active
color
—
--avonni-dd-list-header-actions-color-border-hover
color
—
--avonni-dd-list-header-actions-text-color
color
—
--avonni-dd-list-header-actions-text-color-active
color
—
--avonni-dd-list-header-actions-text-color-hover
color
—
--avonni-dd-list-header-caption-font-family
string
—
--avonni-dd-list-header-caption-font-size
dimension
—
--avonni-dd-list-header-caption-font-style
string
normal
--avonni-dd-list-header-caption-font-weight
number
400
--avonni-dd-list-header-caption-letter-spacing
string
—
--avonni-dd-list-header-caption-line-height
string
—
--avonni-dd-list-header-caption-text-color
color
#000000
--avonni-dd-list-header-color-background
color
—
--avonni-dd-list-header-color-border
color
—
--avonni-dd-list-header-color-border-bottom
color
#c9c9c9
--avonni-dd-list-header-icon-color-background
color
—
--avonni-dd-list-header-icon-color-foreground
color
—
--avonni-dd-list-header-icon-color-foreground-default
color
—
--avonni-dd-list-header-icon-radius-border
string
—
--avonni-dd-list-header-margin-block-end
dimension
—
--avonni-dd-list-header-radius-border
string
—
--avonni-dd-list-header-sizing-border
string
—
--avonni-dd-list-header-sizing-border-bottom
dimension
1px
--avonni-dd-list-header-spacing-block-end
dimension
0.75rem
--avonni-dd-list-header-spacing-block-start
dimension
0.75rem
--avonni-dd-list-header-spacing-inline-end
dimension
1rem
--avonni-dd-list-header-spacing-inline-start
dimension
1rem
--avonni-dd-list-header-styling-border
string
—
--avonni-dd-list-header-styling-border-bottom
string
solid
--avonni-dd-list-header-title-font-family
string
—
--avonni-dd-list-header-title-font-size
dimension
1rem
--avonni-dd-list-header-title-font-style
string
normal
--avonni-dd-list-header-title-font-weight
number
400
--avonni-dd-list-header-title-letter-spacing
string
—
--avonni-dd-list-header-title-line-height
number
1.25
--avonni-dd-list-header-title-text-color
color
#080707
--avonni-dd-list-item-cursor
string
pointer
--avonni-dd-list-item-info-link-text-color
color
#0176d3
--avonni-dd-list-item-info-link-text-color-hover
color
#014486
--avonni-dd-list-item-shadow
string
0 2px 2px 0 rgba(0, 0, 0, 0.1)
--avonni-dd-list-pagination-active-button-color-background
color
#0176d3
--avonni-dd-list-pagination-active-button-color-background-active
color
#014486