Carousel

avonni-carousel

Displays a collection of items in a rotating carousel, with navigation controls and optional autoplay.

Overview

Carousel is a Lightning Web Component that displays a rotating series of items—images, titles, descriptions, and actions—across one or more navigable panels.

Use it in your own Lightning Web Components to showcase featured content, product galleries, or step-by-step highlights. You control the items, how many appear per panel, auto-scroll behavior, the position and style of actions, and the progress indicator—all through the component's attributes.

Use Cases

• Featured content: Rotate promotional banners or highlighted records.
• Product galleries: Display multiple products per panel with quick actions.
• Image showcases: Present a series of images with captions and descriptions.
• Onboarding tours: Walk users through steps with manual or auto navigation.
• Responsive grids: Show more items per panel as the container grows.
• Infinite browsing: Loop continuously through a long set of items.

---

Responsive Guidelines

Property	Use Case
small-items-per-panel	Items per panel when the container is 480px or wider.
medium-items-per-panel	Items per panel when the container is 768px or wider.
large-items-per-panel	Items per panel when the container is 1024px or wider.

---

Use Case Examples

Example 1: Image showcase with infinite scroll

Scenario: Rotate a set of destination images, one per panel, looping continuously every six seconds.

<!-- destinationGallery.html -->
<template>
    <avonni-carousel
        items={items}
        items-per-panel="1"
        current-panel="forest-trail"
        crop-fit="cover"
        image-position="top"
        indicator-variant="base"
        scroll-duration="6"
        is-infinite
    ></avonni-carousel>
</template>

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

export default class DestinationGallery extends LightningElement {
    items = [
        {
            name: 'mountain-lake',
            title: 'Mountain Lake',
            description: 'A serene alpine lake surrounded by snow-capped peaks.',
            imageAssistiveText: 'Mountain lake at dawn'
        },
        {
            name: 'forest-trail',
            title: 'Forest Trail',
            description: 'A winding path through an old-growth coniferous forest.',
            imageAssistiveText: 'Forest trail in autumn'
        }
    ];
}

Result: A single-panel carousel that auto-advances through each destination and loops back to the first when it reaches the end.

Example 2: Gallery with item actions

Scenario: Let users trigger actions (view, share) on each carousel item and react when a panel changes.

<!-- productCarousel.html -->
<template>
    <avonni-carousel
        items={items}
        actions-position="bottom-center"
        actions-variant="border"
        onactionclick={handleActionClick}
        onitemclick={handleItemClick}
        oncurrentpanelchange={handleCurrentPanelChange}
    ></avonni-carousel>
</template>

// productCarousel.js
import { LightningElement } from 'lwc';

const ACTIONS = [
    { label: 'View', name: 'view', iconName: 'utility:preview' },
    { label: 'Share', name: 'share', iconName: 'utility:share' }
];

export default class ProductCarousel extends LightningElement {
    items = [
        { name: 'mountain-lake', title: 'Mountain Lake', actions: ACTIONS },
        { name: 'forest-trail', title: 'Forest Trail', actions: ACTIONS }
    ];

    handleActionClick(event) {
        const actionName = event.detail.name; // 'view' or 'share'
        const item = event.detail.item;
    }

    handleItemClick(event) {
        const item = event.detail.item;
    }

    handleCurrentPanelChange(event) {
        const panelName = event.detail.name;
    }
}

Result: A carousel where each item renders bordered action buttons; clicking an action fires actionclick with the action name and its item.

---

Specifications

Attributes

Name	Description	Type	Default	Required
actions-position	Position of the actions. Valid values include top-left, top-right, bottom-left, bottom-right and bottom-center.	String	"bottom-center"
actions-variant	Changes the appearance of the actions. Valid values include bare, border, menu and stretch.	String	"border"
assistive-text	Description of the carousel items for screen-readers.	AvonniCarouselAssistiveText	"<code>{ autoplayButton: 'Play / Stop auto-play', nextPanel: 'Next Panel', previousPanel: 'Previous Panel' }</code>"
crop-fit	Image fit behaviour inside its container. Valid values include cover, contain, fill and none.	String	"cover"
current-panel	Dictates the currently active/visible carousel panel. Use item’s name to select current panel.	String	—
disable-auto-scroll	If present, images do not automatically scroll and users must click the indicators to scroll.	Boolean	false
hide-indicator	If present, the progress indicator is hidden.	Boolean	false
hide-previous-next-panel-navigation	If present, the left and right arrows of the carousel are hidden.	Boolean	false
image-error-label	Text shown when an image fails to load.	String	"'No Preview Available'"
image-position	Position of the media. Valid values include top, left, right and bottom.	String	"top"
indicator-variant	Changes the appearance of the progress indicators. Valid values are base or shaded.	String	"base"
is-infinite	If present, the carousel will loop when reaching the last panel.	Boolean	false
is-loading	If present, the carousel is in a loading state and shows the loading spinner.	Boolean	false
items	Array of item objects to display in the carousel.	AvonniCarouselItem[]	—	Yes
items-per-panel	Number of items to be displayed at a time in the carousel. Maximum of 10 items per panel.	Number	1
large-items-per-panel	Number of items to be displayed at a time in the carousel when the component is 1024px wide or more. Maximum of 10 items per panel.	Number	—
load-more-offset	Number of hidden panels left when the loadmore event should be fired. For example, if the value is 2, the loadmore event will be fired when the user clicks on the “next” navigation button, and from this screen, they could click two more times on “next” before reaching the end of the items. Depends on enable-infinite-loading being true.	Number	3
max-indicator-items	Maximum number of panels displayed in the indicator. If empty, one dot will be displayed for each panel.	Number	—
medium-items-per-panel	Number of items to be displayed at a time when the component is 768px wide or more. Maximum of 10 items per panel.	Number	—
no-image-label	Text shown when no src is provided.	String	"'No Image Source Provided'"
scroll-duration	Auto scroll delay. The default is 5 seconds, after which the next image is displayed.	Number	5
small-items-per-panel	Number of items to be displayed at a time when the component is 480px wide or more. Maximum of 10 items per panel.	Number	—

Methods

Name	Description	Argument Name	Argument Type	Argument Description
first	Go to first slide.
focus	Set the focus on the first focusable element.
last	Go to last slide.
next	Go to next slide.
pause	Pause the slide cycle.
play	Play the slide cycle.
previous	Go to previous slide.

Custom Events

actionclick

The event fired when a user clicks on an action.

The actionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.
item	object	Item the action belongs to.

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.

blur

The event fired when the focus is removed from the carousel.

The blur event doesn't return any parameters.

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.

currentpanelchange

The event fired when the currently visible panel changes.

The currentpanelchange event returns the following parameters.

Parameter	Type	Description
name	string	Name of the panel's first 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.

focus

The event fired when the focus is set on the carousel.

The focus event doesn't return any parameters.

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

The event fired when an item is clicked.

The itemclick event returns the following parameters.

Parameter	Type	Description
item	object	The item data 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.

loadmore

The event fired when more items should be loaded.

The loadmore event doesn't return any parameters.

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

The event fired when a user clicks on an action.

The actionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.
item	object	Item the action belongs to.

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.

blur

The event fired when the focus is removed from the carousel.

The blur event doesn't return any parameters.

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.

currentpanelchange

The event fired when the currently visible panel changes.

The currentpanelchange event returns the following parameters.

Parameter	Type	Description
item	object	Data of the panel's first item.
name	string	Name of the panel's first 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.

focus

The event fired when the focus is set on the carousel.

The focus event doesn't return any parameters.

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

The event fired when an item is clicked.

The itemclick event returns the following parameters.

Parameter	Type	Description
item	object	The item data 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.

loadmore

The event fired when more items should be loaded.

The loadmore event doesn't return any parameters.

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-carousel-item-color-background	color	#ffffff
--avonni-carousel-item-color-border	color	#c9c9c9
--avonni-carousel-item-sizing-border	sizing	1px
--avonni-carousel-item-styling-border	styling	solid
--avonni-carousel-item-radius-border	radius	0.25rem
--avonni-carousel-item-content-radius-border	radius	0.25rem
--avonni-carousel-item-title-text-color	color	#080707
--avonni-carousel-item-title-font-size	font	1rem
--avonni-carousel-item-title-font-style	font	normal
--avonni-carousel-item-title-font-weight	font	600
--avonni-carousel-item-description-text-color	color	#080707
--avonni-carousel-item-description-font-size	font	0.8125rem
--avonni-carousel-item-description-font-style	font	normal
--avonni-carousel-item-description-font-weight	font	400
--avonni-carousel-item-image-color-background	color	#ffffff
--avonni-carousel-item-image-sizing-height	length-percentage	—
--avonni-carousel-item-image-positioning-object-position	length-percentage	—
--avonni-carousel-item-image-radius-border	radius	0.25rem
--avonni-carousel-item-title-line-clamp	number	2
--avonni-carousel-active-indicator-color-background	color	#0176d3
--avonni-carousel-active-indicator-color-background-hover	color	#0176d3
--avonni-carousel-active-indicator-color-border	color	#0176d3
--avonni-carousel-active-indicator-color-border-hover	color	#0176d3
--avonni-carousel-active-indicator-shaded-color-background	color	#dddbda
--avonni-carousel-active-indicator-shaded-color-background-hover	color	#dddbda
--avonni-carousel-active-indicator-shaded-color-border	color	#dddbda
--avonni-carousel-active-indicator-shaded-color-border-hover	color	#dddbda
--avonni-carousel-inactive-indicator-color-background	color	#ffffff
--avonni-carousel-inactive-indicator-color-background-hover	color	#fafaf9
--avonni-carousel-inactive-indicator-color-border	color	#747474
--avonni-carousel-inactive-indicator-color-border-hover	color	#747474
--avonni-carousel-inactive-indicator-shaded-color-background	color	#ffffff
--avonni-carousel-inactive-indicator-shaded-color-border	color	#747474
--avonni-carousel-navigation-button-color-background	color	white
--avonni-carousel-navigation-button-sizing-border	sizing	1px
--avonni-carousel-navigation-button-styling-border	styling	solid
--avonni-carousel-navigation-button-color-border	color	#747474
--avonni-carousel-navigation-icon-color	color	#747474
--avonni-carousel-navigation-button-color-background-hover	color	white
--avonni-carousel-navigation-button-sizing-border-hover	sizing	1px
--avonni-carousel-navigation-button-styling-border-hover	styling	solid
--avonni-carousel-navigation-button-color-border-hover	color	#747474
--avonni-carousel-navigation-icon-color-hover	color	#014486
--avonni-carousel-navigation-button-color-border-disabled	color	#747474
--avonni-carousel-navigation-button-color-background-disabled	color	white
--avonni-carousel-navigation-icon-color-disabled	color	#c9c9c9
--avonni-carousel-item-action-bare-color-background	color	transparent
--avonni-carousel-item-action-bare-text-color	color	#0176d3
--avonni-carousel-item-action-bare-color-border	color	transparent
--avonni-carousel-item-action-bare-sizing-border	sizing	1px
--avonni-carousel-item-action-bare-styling-border	styling	solid
--avonni-carousel-item-action-bare-radius-border	dimension	0.25rem
--avonni-carousel-item-action-bare-color-background-hover	color	transparent
--avonni-carousel-item-action-bare-text-color-hover	color	#014486
--avonni-carousel-item-action-bare-color-border-hover	color	transparent
--avonni-carousel-item-action-bare-color-background-active	color	transparent
--avonni-carousel-item-action-bare-text-color-active	color	#014486
--avonni-carousel-item-action-bare-color-border-active	color	transparent
--avonni-carousel-item-action-neutral-color-background	color	white
--avonni-carousel-item-action-neutral-text-color	color	#0176d3
--avonni-carousel-item-action-neutral-color-border	color	#747474
--avonni-carousel-item-action-neutral-sizing-border	sizing	1px
--avonni-carousel-item-action-neutral-styling-border	styling	solid
--avonni-carousel-item-action-neutral-radius-border	dimension	0.25rem
--avonni-carousel-item-action-neutral-color-background-hover	color	#f3f3f3
--avonni-carousel-item-action-neutral-text-color-hover	color	#014486
--avonni-carousel-item-action-neutral-color-border-hover	color	#747474
--avonni-carousel-item-action-neutral-color-background-active	color	#f3f3f3
--avonni-carousel-item-action-neutral-text-color-active	color	#014486
--avonni-carousel-item-action-neutral-color-border-active	color	#747474
--avonni-carousel-item-action-button-menu-color-background	color	#ffffff
--avonni-carousel-item-action-button-menu-text-color	color	#747474
--avonni-carousel-item-action-button-menu-color-border	color	#747474
--avonni-carousel-item-action-button-menu-color-background-hover	color	#ffffff
--avonni-carousel-item-action-button-menu-text-color-hover	color	#014486
--avonni-carousel-item-action-button-menu-color-border-hover	color	#747474
--avonni-carousel-item-action-button-menu-color-background-active	color	#ffffff
--avonni-carousel-item-action-button-menu-text-color-active	color	#014486
--avonni-carousel-item-action-button-menu-color-border-active	color	#014486
--avonni-carousel-item-action-button-menu-sizing-border	sizing	1px
--avonni-carousel-item-action-button-menu-styling-border	styling	solid
--avonni-carousel-item-action-button-menu-radius-border	dimension	0.25rem

Key Considerations

• Unique names: Each item's name drives navigation, current-panel, and event payloads—keep them unique.
• Responsive panels: Combine items-per-panel with the small/medium/large variants to adapt the layout to the container width.
• Auto-scroll: Set disable-auto-scroll for static galleries, or tune scroll-duration to control pacing.
• Lazy loading: Use loadmore with is-infinite to fetch items on demand.
• Accessibility: Provide assistive-text so screen readers describe the navigation controls.
• Best Practice: Always give each item a unique name so current-panel, currentpanelchange, and action events can reliably identify panels.

---

Troubleshooting Common Issues

• Panel not showing: Verify current-panel matches an existing item name.
• Auto-scroll not working: Confirm disable-auto-scroll is not set and scroll-duration is a positive number.
• Action click not firing: Ensure each item has an actions array and the onactionclick handler is wired in the template.
• If issues persist: Contact our support team at [email protected] for assistance.