> 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/dynamic-components/components/carousel.md).

# Carousel

The Avonni Carousel component displays a collection of items — images, text, and actions — in an interactive, sliding set of panels. It is ideal for highlighting features, browsing visual galleries, or guiding users through a sequence of content within a fixed area.

## Overview

The Carousel optimizes screen real estate by cycling through content in horizontal panels. It supports a configurable number of items per panel at each breakpoint, optional infinite looping, auto-scroll timing, progress indicators, navigation arrows, clickable items, and an optional actions overlay, with built-in assistive text for accessibility.

### Common Use Cases

| Use Case             | Description                                                     | Example                                                                    |
| -------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Product Showcase** | Specific featured items or new arrivals in a horizontal scroll. | A "New Arrivals" section on a Home Page showing product images and prices. |
| **Image Gallery**    | A visual portfolio or event recap.                              | Displaying photos from a recent site visit or marketing event.             |
| **Testimonials**     | Cycle through social proof without taking up vertical space.    | A single-item slider showing quotes and client names.                      |
| **Onboarding/Steps** | Guide users through a linear process.                           | A "How it Works" carousel with 3 slides: Step 1, Step 2, and Step 3.       |

## Configuration

To configure the Carousel, select it on the canvas. The **Edit Carousel** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab.

### Data Source

Before you build your carousel, you must tell the Avonni Carousel component where to get the items it should display. You have several options, depending on the source and nature of your data:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Manual</strong></td><td>Enter data directly into the component configuration.</td><td></td></tr><tr><td><strong>Variable</strong></td><td>This is useful for data that changes based on user interactions or other component logic.</td><td></td></tr><tr><td><strong>Query</strong></td><td>This is the most common option for displaying Salesforce records.</td><td></td></tr></tbody></table>

### Data Mapping

When using a dynamic data source (Query or Variable), you'll need to configure the **Data Mappings** section to tell the component how to turn each record into a carousel item.

Think of it like a translator: Data Mappings connect the fields on your Salesforce records to the attributes the carousel displays.

<table><thead><tr><th width="180">Carousel Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>Title</strong></td><td>The primary string used as the item heading.</td></tr><tr><td><strong>Description</strong></td><td>A secondary string that describes the item (rich text supported).</td></tr><tr><td><strong>Image Source</strong></td><td>The URL or Content Document ID of the item image.</td></tr><tr><td><strong>Image Assistive Text</strong></td><td>Alt text for the image. If not provided, the title is used instead.</td></tr><tr><td><strong>URL</strong></td><td>Address of the web page the item links to.</td></tr><tr><td><strong>Target</strong></td><td>Controls where the URL opens — current tab (default), new tab, parent frame, or full window. Requires a <strong>URL</strong> to be set.</td></tr><tr><td><strong>Key Field</strong></td><td>Unique identifier of the carousel item (defaults to the record Id).</td></tr></tbody></table>

### Content

The Content section controls how the carousel behaves and advances.

* **Hide Navigation**: Hides the left and right navigation arrows.
* **Items Clickable**: When enabled, every item in the carousel can be clicked.

The following settings are available with a Manual data source:

* **Is Infinite**: When enabled, the carousel loops back to the first panel after reaching the last one.
* **Disable Auto Refresh**: When enabled, the carousel does not loop after the last image is displayed.
* **Disable Auto Scroll**: When enabled, images do not advance automatically — users navigate using the indicators.
* **Current Item Name**: The name of the item that should be visible on initial load. When set, the carousel first loads with that item shown.
* **Scroll Duration**: The auto-scroll interval before the next panel is displayed. The default is 5 seconds.

### Layout

The Layout section controls how many items appear at once, with separate values for each breakpoint so the carousel adapts across devices. Each value accepts up to 10 items per panel.

* **Items per panel**: The default number of items shown at a time (defaults to 1 — a "Hero Banner" feel; raise it for a "Product Shelf" feel). Maximum 10.
* **Small Items per panel**: Items shown when the component is at least 480px wide.
* **Medium Items per panel**: Items shown when the component is at least 768px wide.
* **Large Items per panel**: Items shown when the component is at least 1024px wide.

### Image

* **Crop Fit**: How each item image fits inside its container — **Cover** (default), **Contain**, **Fill**, or **None**.

### Indicator

The Indicator section controls the progress dots beneath the carousel.

* **Hide Indicator**: Hides the progress indicator.
* **Indicator Variant**: Changes the appearance of the indicators — **Base** (default) or **Shaded**. Requires the indicator to be visible.
* **Maximum Number of Indicator Items**: The maximum number of indicators visible at once. Defaults to 5 when there are more than 25 items. Requires the indicator to be visible.

### Actions

The Actions section adds interactive buttons that overlay each carousel item. Trigger their behavior from the **Item Action Click** interaction.

* **Actions**: The list of actions to display. Each action defines a **Label**, a unique **Name**, an optional **Icon Name**, and **Alternative Text** describing the icon.
* **Position**: Where the actions appear on the item — **Bottom Center** (default), **Bottom Left**, **Bottom Right**, **Top Left**, or **Top Right**.
* **Variant**: The action button style — **Bare**, **Border** (default), **Menu**, or **Stretch**.

### Assistive Text

The Assistive Text section provides screen-reader labels for the carousel controls.

* **Autoplay Button**: Label for the autoplay control (default "Start / Stop auto-play").
* **Next Panel**: Label for the next-panel arrow (default "Next Panel").
* **Previous Panel**: Label for the previous-panel arrow (default "Previous Panel").

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Interactions

[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Carousel. Configure them from the **Interactions** tab of the Edit Carousel panel.

### Item Click

Fires when a user clicks an item in the carousel. Requires **Items Clickable** to be enabled. Use this to navigate to a detail page, open a modal, or trigger any flow logic tied to the selected item.

### Item Action Click

Fires when a user clicks one of the action buttons overlaid on a carousel item. Use the **targetName** output to identify which action was clicked and branch your flow logic accordingly.

### Current Item Change

Fires whenever the visible item changes as the carousel advances to a new panel. This interaction does not fire on initial load — only when the current item changes after the carousel has first rendered.

## Styling

The Avonni Carousel offers extensive styling options. Configure them from the **Style** tab of the Edit Carousel panel.

{% tabs %}
{% tab title="Margin" %}
Controls the *outer* spacing around the carousel.

* **Top / Right / Bottom / Left:** Adjust the space on each side of the carousel.
  {% endtab %}

{% tab title="Padding" %}
Controls the *inner* spacing inside the carousel container.

* **Top / Right / Bottom / Left:** Adjust the inner spacing on each side.
  {% endtab %}

{% tab title="Border" %}
Customizes the border surrounding the carousel.

* **Color / Size / Style / Radius:** Customize the carousel border.
  {% endtab %}

{% tab title="Size" %}
Controls the carousel's dimensions.

* **Width / Height:** Set fixed dimensions for the carousel.
* **Overflow:** Control how content that exceeds the bounds is handled.
* **Min Width / Max Width / Min Height / Max Height:** Constrain the size within bounds.
  {% endtab %}

{% tab title="Item" %}

* **Background Color:** Set the item background color.
* **Border Color / Border Size / Border Style / Border Radius:** Customize each item's border.
* **Content Border Radius:** Round the corners of the item content area.
  {% endtab %}

{% tab title="Item Title" %}

* **Color:** Set the item title color.
* **Font Size / Font Style / Font Weight:** Control the item title typography.
  {% endtab %}

{% tab title="Image" %}

* **Background Color:** Set the item image background color.
* **Height:** Set the image height.
* **Radius:** Round the corners of the item image.
  {% endtab %}

{% tab title="Item Description" %}

* **Color:** Set the item description color.
* **Font Size / Font Style / Font Weight:** Control the item description typography.
  {% endtab %}

{% tab title="Active Indicator" %}

* **Background Color / Border Color** (with hover and shaded variants)**:** Style the active indicator.
  {% endtab %}

{% tab title="Inactive Indicator" %}

* **Background Color / Border Color** (with hover and shaded variants)**:** Style inactive indicators.
  {% endtab %}

{% tab title="Navigation Button" %}

* **Background Color / Icon Color / Border Color, Size, Style:** Style the navigation arrows across default, hover, and disabled states.
  {% endtab %}

{% tab title="Action Button Bare" %}

* **Background Color / Text Color / Border Color, Size, Radius:** Style bare-variant action buttons across default, active, and hover states.
  {% endtab %}

{% tab title="Action Button Border" %}

* **Background Color / Text Color / Border Color, Size, Radius:** Style border-variant action buttons across default, active, and hover states.
  {% endtab %}
  {% endtabs %}

## Output Variables

The Carousel exposes these output variables you can reference elsewhere on the page after the user interacts with it.

### Item Click

When a user clicks an item in the carousel, these variables update with the clicked item's data. Requires **Items Clickable** to be enabled.

| Output variable          | Type             | What it returns                                                                                                |
| ------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------- |
| **Clicked Item**         | Object           | The clicked item's data — its title, description, image source, URL, and other item attributes.                |
| **Clicked Item sObject** | Record (SObject) | The full Salesforce record associated with the clicked item. Requires a **Query** or **Variable** data source. |

> **Example:** When a user clicks a product card in the carousel, use **Clicked Item sObject** to populate a record-detail component beside the carousel with that product's full details.

### Item Action Click

When a user clicks one of the action buttons overlaid on a carousel item, these variables update with the action's details.

| Output variable                        | Type             | What it returns                                                                                                            |
| -------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Clicked Item Action - Action Name**  | Text (String)    | The name of the action button the user clicked. Use this to branch logic when multiple actions are configured.             |
| **Clicked Item Action - Item**         | Object           | The item on which the action was clicked — its title, description, image source, URL, and other item attributes.           |
| **Clicked Item Action - Item sObject** | Record (SObject) | The full Salesforce record for the item on which the action was clicked. Requires a **Query** or **Variable** data source. |

> **Example:** When a carousel of opportunities has "Qualify" and "Disqualify" actions, use **Clicked Item Action - Action Name** to route to the appropriate update flow and **Clicked Item Action - Item sObject** to identify which opportunity to update.

### Current Item Change

When the visible panel changes — by auto-scroll, navigation arrows, or indicators — these variables update with the newly visible item's data.

| Output variable          | Type             | What it returns                                                                                              |
| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------ |
| **Current Item**         | Object           | The currently visible item's data — its title, description, image source, URL, and other item attributes.    |
| **Current Item sObject** | Record (SObject) | The full Salesforce record for the currently visible item. Requires a **Query** or **Variable** data source. |

> **Example:** Sync a detail panel beside the carousel with whatever item is currently in view by binding it to **Current Item sObject** — the panel refreshes automatically as the carousel advances.

### Others

| Output variable     | Type   | What it returns                                   |
| ------------------- | ------ | ------------------------------------------------- |
| **Number of Items** | Number | The total number of items loaded in the carousel. |


---

# 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/dynamic-components/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.