> 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/image-list.md).

# 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.

```html
<!-- 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>
```

```js
// 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.

```html
<!-- 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>
```

```js
// destinationGallery.js
import { LightningElement } from 'lwc';

export default class DestinationGallery extends LightningElement {
    items = [
        {
            label: 'Mountain Lake',
            name: 'mountain-lake',
            description: 'A serene alpine lake surrounded by snow-capped peaks.',
            imageSrc: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600'
        },
        {
            label: 'Forest Trail',
            name: 'forest-trail',
            description: 'A winding path through an old-growth coniferous forest.',
            imageSrc: 'https://images.unsplash.com/photo-1448375240586-882707db888b?w=600'
        }
    ];

    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) {
        // In static mode itemSObject is null; the tile data is in event.detail.item
        const { name, item } = event.detail;
    }
    handleItemClick(event) {
        const item = event.detail.item;
    }
    handlePageChange(event) {
        const page = event.detail.value;
    }
}
```

**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`      |          |
| `header-caption`          | Header caption, displayed above the title.                                                                                                                                                                                                                                              | String                        | —        |          |
| `header-show-items-count` | If true, the number of items found is displayed in the header.                                                                                                                                                                                                                          | Boolean                       | `false`  |          |
| `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 | —        |          |
| `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`  |          |
| `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                       | —        |          |
| `variant`                 | The variant changes the appearance of the image list. Valid values are `base`, `quilted`, `woven` and `masonry`.                                                                                                                                                                        | String                        | `"base"` |          |

### 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.    |
| `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 <support@avonni.app> 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/image-list.md?ask=<question>&goal=<endgoal>
```

`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.