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.

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

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

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

// 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 [email protected] for assistance.