> 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/lwc-components/data-driven-components/list.md).
# 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 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.
```html
```
```js
// accountList.js
import { LightningElement } from 'lwc';
export default class AccountList extends LightningElement {
accountQuery = { objectApiName: 'Account', orderBy: 'Name ASC', limit: 50 };
accountMapping = {
label: '{{Record.Name}}',
name: '{{Record.Id}}',
description: '{{Record.Industry}}',
avatar: { fallbackIconName: 'standard:account' }
};
accountSearchFields = ['Name'];
accountFilters = ['Industry', 'BillingState'];
actions = [
{ label: 'See more', name: 'seeMore', iconName: 'utility:preview' },
{ label: 'Delete', name: 'delete', iconName: 'utility:delete' }
];
avatarAttributes = { variant: 'circle', size: 'large' };
paginationAttributes = { align: 'center' };
handleItemClick(event) {
const { item, itemSObject } = event.detail; // itemSObject is the record
}
handleActionClick(event) {
const { name, item, itemSObject } = event.detail;
}
handleError(event) {
const message = event.detail.message;
}
}
```
**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.
```html
```
```js
// featuredList.js
import { LightningElement } from 'lwc';
export default class FeaturedList extends LightningElement {
items = [
{
label: 'Mountain Lake',
name: 'mountain-lake',
description: 'A serene alpine lake surrounded by snow-capped peaks.',
avatar: { fallbackIconName: 'standard:location', initials: 'ML' }
},
{
label: 'Forest Trail',
name: 'forest-trail',
description: 'A winding path through an old-growth coniferous forest.',
avatar: { fallbackIconName: 'standard:location', initials: 'FT' }
}
];
actions = [
{ label: 'See more', name: 'seeMore', iconName: 'utility:preview' },
{ label: 'Delete', name: 'delete', iconName: 'utility:delete' }
];
avatarAttributes = { fallbackIconName: 'standard:location', variant: 'circle', size: 'large' };
paginationAttributes = { align: 'center' };
handleItemClick(event) {
const { item } = event.detail; // itemSObject is null in static mode
}
handleActionClick(event) {
const { name, item } = event.detail;
}
}
```
**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
| 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 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"` | |
| `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' }`.
```js
const ACCOUNT_MAPPING = {
label: '{{Record.Name}}',
name: '{{Record.Id}}',
description: '{{Record.Industry}}',
avatar: { fallbackIconName: 'standard:account' }
};
```
In static mode, supply the same shape directly in the `items` array (no `{{Record.*}}` placeholders—use literal values).
### 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. |
### Custom Events
#### `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. |
#### `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. |
### Styling Hooks
| CSS Variable | Type | Default |
| ------------------------------------------------------------------- | --------- | -------------------------------- |
| `--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` |
| `--avonni-dd-list-pagination-active-button-color-background-hover` | color | `#014486` |
| `--avonni-dd-list-pagination-active-button-color-border` | color | `#0176d3` |
| `--avonni-dd-list-pagination-active-button-color-border-active` | color | `#014486` |
| `--avonni-dd-list-pagination-active-button-color-border-hover` | color | `#014486` |
| `--avonni-dd-list-pagination-active-button-text-color` | color | `#fff` |
| `--avonni-dd-list-pagination-active-button-text-color-active` | color | `#fff` |
| `--avonni-dd-list-pagination-active-button-text-color-hover` | color | `#fff` |
| `--avonni-dd-list-pagination-button-color-background` | color | `#fff` |
| `--avonni-dd-list-pagination-button-color-background-active` | color | `#f3f3f3` |
| `--avonni-dd-list-pagination-button-color-background-disabled` | color | `#fff` |
| `--avonni-dd-list-pagination-button-color-background-hover` | color | `#f3f3f3` |
| `--avonni-dd-list-pagination-button-color-border` | color | `#747474` |
| `--avonni-dd-list-pagination-button-color-border-active` | color | `#747474` |
| `--avonni-dd-list-pagination-button-color-border-disabled` | color | `#747474` |
| `--avonni-dd-list-pagination-button-color-border-hover` | color | `#747474` |
| `--avonni-dd-list-pagination-button-sizing-border` | dimension | `1px` |
| `--avonni-dd-list-pagination-button-styling-border` | string | `solid` |
| `--avonni-dd-list-pagination-button-text-color` | color | `#0176d3` |
| `--avonni-dd-list-pagination-button-text-color-active` | color | `#014486` |
| `--avonni-dd-list-pagination-button-text-color-disabled` | color | `#c9c9c9` |
| `--avonni-dd-list-pagination-button-text-color-hover` | color | `#014486` |
| `--avonni-dd-list-show-more-button-color-background` | color | — |
| `--avonni-dd-list-show-more-button-color-background-active` | color | — |
| `--avonni-dd-list-show-more-button-color-background-hover` | color | — |
| `--avonni-dd-list-show-more-button-color-border` | color | — |
| `--avonni-dd-list-show-more-button-color-border-active` | color | — |
| `--avonni-dd-list-show-more-button-color-border-hover` | color | — |
| `--avonni-dd-list-show-more-button-radius-border` | string | — |
| `--avonni-dd-list-show-more-button-sizing-border` | string | — |
| `--avonni-dd-list-show-more-button-spacing-block-end` | dimension | — |
| `--avonni-dd-list-show-more-button-spacing-block-start` | dimension | — |
| `--avonni-dd-list-show-more-button-spacing-inline-end` | dimension | — |
| `--avonni-dd-list-show-more-button-spacing-inline-start` | dimension | — |
| `--avonni-dd-list-show-more-button-text-color` | color | — |
| `--avonni-dd-list-show-more-button-text-color-active` | color | — |
| `--avonni-dd-list-show-more-button-text-color-hover` | color | — |
## Key Considerations
* **One mode at a time:** Setting `items` puts the list in static mode and ignores `query` and `mapping`; clear `items` to return to query mode.
* **No record in static mode:** In static mode, `itemSObject` is `null` in events—rely on the `item` property to identify the clicked item.
* **Item clicks:** `itemclick` only fires when `allow-item-click` is set.
* **Sorting limits:** `sortable` works only with the `base` variant in a single column; it is not supported across multiple columns.
* **Mapping syntax:** In query mode, every field referenced via `{{Record.FieldApiName}}` or listed in `fields` must exist on the queried object and be accessible to the running user.
* **Best Practice:** Pick one mode per list—set `items` for static content, or `query` + `mapping` for live data. In query mode, keep `fields` minimal and use `mapping` label/description for the primary information.
***
## Troubleshooting Common Issues
* **List is empty in query mode:** Confirm `query.objectApiName` is correct, the filter returns rows, and the `mapping` uses `{{Record.FieldApiName}}` syntax.
* **Static items not showing:** Ensure `items` is a non-empty array and that you have not also expected `query`/`mapping` to take effect—static `items` override them.
* **Clicks not firing:** Set `allow-item-click` for `itemclick`, and confirm the matching `on*` handlers are wired in the template.
* **If issues persist:** Contact our support team at for assistance.
---
# 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/lwc-components/data-driven-components/list.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.