> 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/carousel.md).
# Carousel
`avonni-dd-carousel`
The Avonni Data Driven Carousel displays records in horizontal sliding panels.
## Overview
**Carousel** is a data-driven Lightning Web Component that displays records as a set of horizontal sliding panels, each showing an image, title, and description.
It runs in two modes. In **query mode** you set a `query` object and a `mapping` object: the component runs the query, maps each record's fields to carousel item properties using the `{{Record.FieldApiName}}` syntax, and renders the panels automatically. In **static mode** you set the `items` array directly and the component ignores `query` and `mapping`. It inherits the shared Data Driven API (query, mapping, filters, search, header) from the base element.
### Use Cases
* **Featured records:** Showcase top accounts, products, or campaigns as image panels that auto-advance.
* **File galleries:** Browse `ContentDocument` images pulled straight from a query.
* **Promotional banners:** Display a fixed set of static marketing slides without any data source.
* **Record navigation:** Let users click a panel to open the related record detail page.
* **Responsive showcases:** Show a different number of items per panel based on the container width.
* **Action surfaces:** Overlay per-item actions (preview, delete) on every panel.
***
## Use Case Examples
### Example 1: Query mode
**Scenario:** Display the most recent Accounts as a responsive carousel, with a distinct image per record and per-item actions.
```html
```
```js
// accountCarousel.js
import { LightningElement } from 'lwc';
export default class AccountCarousel extends LightningElement {
accountQuery = {
objectApiName: 'Account',
orderBy: 'Name ASC',
limit: 50
};
accountMapping = {
title: '{{Record.Name}}',
name: '{{Record.Id}}',
description: '{{Record.Industry}}',
src: 'https://api.dicebear.com/9.x/shapes/png?size=320&seed={{Record.Id}}'
};
actions = [
{ label: 'See more', name: 'seeMore', iconName: 'utility:preview' },
{ label: 'Delete', name: 'delete', iconName: 'utility:delete' }
];
handleActionClick(event) {
const { name, item, itemSObject } = event.detail; // record in itemSObject
}
handleCurrentItemChange(event) {
const { name } = event.detail;
}
handleItemClick(event) {
const { itemSObject } = event.detail;
}
}
```
**Result:** A carousel of Account panels that auto-advances every six seconds, shows one to two panels depending on width, and reports the underlying record on every event.
### Example 2: Static mode
**Scenario:** Show a fixed gallery of scenic images with no data source, starting on a specific slide and looping infinitely.
```html
```
```js
// gallery.js
import { LightningElement } from 'lwc';
export default class Gallery extends LightningElement {
items = [
{
title: 'Mountain Lake',
name: 'mountain-lake',
description: 'A serene alpine lake surrounded by snow-capped peaks.',
src: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600'
},
{
title: 'Coastal Cliffs',
name: 'coastal-cliffs',
description: 'Dramatic ocean cliffs at sunset on the Pacific coast.',
src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600'
}
];
actions = [
{ label: 'See more', name: 'seeMore', iconName: 'utility:preview' },
{ label: 'Delete', name: 'delete', iconName: 'utility:delete' }
];
assistiveText = {
autoplayButton: 'Start / stop auto-play',
nextPanel: 'Next panel',
previousPanel: 'Previous panel'
};
handleActionClick(event) {
// itemSObject is null in static mode
}
handleCurrentItemChange(event) {}
handleItemClick(event) {}
}
```
**Result:** A looping carousel that opens on the "Coastal Cliffs" slide; events fire with `itemSObject` set to `null` because no record is associated.
***
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | --------- | -------- |
| `actions` | Array of action objects. The actions are displayed as an overlay on every carousel item. On click on an action, the `actionclick` event is fired. | DdCarouselAction\[] | — | |
| `actions-position` | Position of the item actions overlay. Valid values are `bottom-center`, `bottom-left`, `bottom-right`, `top-left` and `top-right`. | String | — | |
| `actions-variant` | Changes the appearance of the item actions. Valid values are `bare`, `border`, `menu` and `stretch`. | String | — | |
| `allow-item-click` | If true, the items are displayed as clickable, and a click on an item fires the `itemclick` event. | Boolean | `false` | |
| `assistive-text` | Object defining the assistive texts used by the carousel controls. | DdCarouselAssistiveText | — | |
| `crop-fit` | Crop fit behaviour of the item images inside their container. Valid values are `cover`, `contain`, `fill` and `none`. | String | `"cover"` | |
| `current-item-name` | Name of the item that should be visible on initial load. The carousel starts on that item. | String | — | |
| `disable-auto-refresh` | If true, the auto-refresh of the carousel is disabled. | Boolean | `false` | |
| `disable-auto-scroll` | If true, the carousel does not automatically scroll to the next panel. | Boolean | `false` | |
| `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-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-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-indicator` | If true, the progress indicator is hidden. | Boolean | `false` | |
| `hide-previous-next-panel-navigation` | If true, the previous and next panel navigation arrows are hidden. | Boolean | `false` | |
| `indicator-variant` | Changes the appearance of the progress indicator. Valid values are `base` and `shaded`. | String | `"base"` | |
| `is-infinite` | If true, the carousel loops back to the first panel after the last one. | Boolean | `false` | |
| `items` | Array of static items displayed in the carousel. When this property is set, the carousel ignores the `query` and `mapping` properties and displays the items directly. | DdCarouselItem\[] | — | |
| `items-per-page` | If the pagination is enabled, number of items per page. Otherwise, number of items loaded at once. | integer | — | |
| `items-per-panel` | Default number of items displayed per panel. Maximum value is 10. | integer | — | |
| `large-items-per-panel` | Number of items displayed per panel when the carousel width is greater or equal to 1024px. Maximum value is 10. | integer | — | |
| `mapping` | Object defining the way the records returned by the query should be mapped to the carousel 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}}`. | DdCarouselMapping | — | |
| `max-indicator-items` | Maximum number of indicator items visible at once. Defaults to 5 when the number of items exceeds 25. | integer | — | |
| `medium-items-per-panel` | Number of items displayed per panel when the carousel width is greater or equal to 768px. Maximum value is 10. | integer | — | |
| `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 | — | |
| `scroll-duration` | Auto-scroll interval in seconds before advancing to the next panel. | Number | `5` | |
| `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\[] | — | |
| `side-panel-attributes` | Object defining the side panel-specific attributes. | DdElementSidePanelAttributes | — | |
| `small-items-per-panel` | Number of items displayed per panel when the carousel width is greater or equal to 480px. Maximum value is 10. | integer | — | |
### 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 tells the carousel how to build each item from a queried record. Insert a field value with the `{{Record.FieldApiName}}` syntax (for example `{{Record.Name}}`). Static text and field references can be combined in a single value.
| Mapping Key | Description |
| -------------------- | ------------------------------------------------------------------------ |
| `title` | Item title, usually `{{Record.Name}}`. |
| `name` | Unique item name, commonly the record `{{Record.Id}}`. |
| `description` | Secondary text shown under the title. |
| `src` | Image URL or `ContentDocument` reference for the panel visual. |
| `imageAssistiveText` | Alternative text for the image. Falls back to the title if not provided. |
| `href` | URL the item links to when clicked. |
| `target` | Where to open the link: `_self`, `_blank`, `_parent`, `_top`. |
### 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 | Carousel item the action belongs to, with the mapped `title`, `name`, `description`, `src`, `href`, `target` and `imageAssistiveText` 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. |
#### `currentitemchange`
Event fired when the visible carousel item changes.
The `currentitemchange` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `item` | object | Carousel item that is now visible, with the mapped `title`, `name`, `description`, `src`, `href`, `target` and `imageAssistiveText` properties. |
| `record` | object | Record corresponding to the visible item. In static mode, no record is associated and this is `null`. |
| `name` | string | Name of the visible item. |
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 | Carousel item that was clicked, with the mapped `title`, `name`, `description`, `src`, `href`, `target` and `imageAssistiveText` 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. |
#### `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. |
#### `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 | Carousel item the action belongs to, with the mapped `title`, `name`, `description`, `src`, `href`, `target` and `imageAssistiveText` 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. |
#### `currentitemchange`
Event fired when the visible carousel item changes.
The `currentitemchange` event returns the following parameters.
| Parameter | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `item` | object | Carousel item that is now visible, with the mapped `title`, `name`, `description`, `src`, `href`, `target` and `imageAssistiveText` properties. |
| `itemSObject` | object | Record corresponding to the visible item. In static mode, no record is associated and this is `null`. |
| `name` | string | Name of the visible item. |
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 | Carousel item that was clicked, with the mapped `title`, `name`, `description`, `src`, `href`, `target` and `imageAssistiveText` 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. |
## Key Considerations
* **Query vs static:** Setting `items` switches the component to static mode and causes `query` and `mapping` to be ignored. Use one mode or the other.
* **Mapping syntax:** Field values are inserted with `{{Record.FieldApiName}}` and can be combined with static text (for example inside an image URL).
* **`itemSObject` in static mode:** Events still fire, but `itemSObject` is `null` since static items are not backed by records.
* **Responsive panels:** `small-`, `medium-`, and `large-items-per-panel` override `items-per-panel` at increasing container widths (max 10 each).
* **Stable names:** Map `name` to the record `Id` in query mode so selection, `current-item-name`, and events stay consistent.
* **Best Practice:** In query mode, always map `name` to the record `Id` so each panel has a stable, unique key and the `currentitemchange` and `actionclick` events report the right record.
***
## Troubleshooting Common Issues
* **Carousel shows nothing in query mode:** Confirm `query.objectApiName` is set and the running user has read access; check the `error` event for query failures.
* **Images not rendering:** Verify the `src` mapping resolves to a reachable URL or a valid `ContentDocument` reference, and that external hosts are CSP Trusted Sites.
* **`items` ignored:** Remember that setting `items` disables `query`/`mapping`; remove `items` to return to query mode.
* **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/carousel.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.