> 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
<!-- accountCarousel.html -->
<template>
    <avonni-dd-carousel
        query={accountQuery}
        mapping={accountMapping}
        actions={actions}
        actions-position="bottom-center"
        actions-variant="border"
        allow-item-click
        crop-fit="cover"
        items-per-panel="1"
        medium-items-per-panel="2"
        large-items-per-panel="2"
        scroll-duration="6"
        onactionclick={handleActionClick}
        oncurrentitemchange={handleCurrentItemChange}
        onitemclick={handleItemClick}
    ></avonni-dd-carousel>
</template>
```

```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
<!-- gallery.html -->
<template>
    <avonni-dd-carousel
        items={items}
        actions={actions}
        actions-position="bottom-center"
        actions-variant="border"
        allow-item-click
        assistive-text={assistiveText}
        crop-fit="cover"
        current-item-name="coastal-cliffs"
        is-infinite
        items-per-panel="1"
        medium-items-per-panel="2"
        large-items-per-panel="3"
        scroll-duration="6"
        onactionclick={handleActionClick}
        oncurrentitemchange={handleCurrentItemChange}
        onitemclick={handleItemClick}
    ></avonni-dd-carousel>
</template>
```

```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`   |          |
| `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                 | —         |          |
| `scroll-duration`                     | Auto-scroll interval in seconds before advancing to the next panel.                                                                                                                                                                                           | Number                  | `5`       |          |
| `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                 | —         |          |

### 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. |
| `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 <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/carousel.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.