> 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/core-components/carousel.md).
# 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.
```html
```
```js
// 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.
```html
```
```js
// 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 | `"{ autoplayButton: 'Play / Stop auto-play', nextPanel: 'Next Panel', previousPanel: 'Previous Panel' }"` | |
| `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 |
| --------- | ------ | ------------------------------- |
| `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 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/core-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.