--- updatedAt: 2026-11-11T09:42:05.000Z agentTools: projectIndex: https://docs.digitalgenius.com/llms.txt --- # Carousel The Carousel component allows you to display a series of slides, such as products or images, in a horizontal or vertical scrollable UI. You can customise the carousel's appearance and functionality with several properties. ## Key Properties: * **slideOrientation**: Defines how the carousel slides are displayed. Use the following values: * **horizontal**: For landscape images. * **vertical**: For portrait images. * **square**: For square images. * **none**: No specific orientation. * **carouselType** (optional): Defines the type of carousel which is used for analytics, e.g. `product-carousel`. A `product-recommendation` carousel also shows a share button on each slide that has an `externalLink` (see [Sharing slides](#sharing-slides)). * **multiSelectEnabled** (optional): When enabled, multiple slides can be selected and submitted. The submitted payload becomes an array of slide ID's. * **enableAddToCart** (optional): When enabled and add to cart is available on the site (a Shopify store, `callbacks.onAddToCart`, or a configured `ecomPlatform` and `cart` request; see [Add to Cart](https://docs.digitalgenius.com/docs/add-to-cart)), the carousel slides will display an "Add to cart" button. * **payload**: An array of objects where each object represents a single slide. The following properties can be included: * **id**: The unique identifier for the slide (e.g., a product). * **trackingId** (optional): Used for analytics tracking, must be a string. * **image**: A URL to the image displayed for the slide. Not required if variants are provided. * **title**: The name/title of the slide. * **price** (optional): Displays the price on the slide (overridden by variant prices, if any). Supports markdown. * **externalLink** (optional): A URL that opens when the slide card is clicked. If no externalLink is provided, clicking the slide sends the carousel select event. * **buttonText** (optional): Used for the slide card's accessible label when no externalLink is provided. * **disabled** (optional): Whether the slide is disabled. * **variants** (optional): If variants are provided, thumbnail buttons for each variant will be displayed. Variant-specific data, such as price, externalLink, trackingId, and sizes, override the top-level values when selected. * **sizes** (optional, requires `enableAddToCart`): Size options to pick before Add to cart (e.g. shoe size, strap length). Can be set on the slide or on each variant — variant sizes win when present. Each entry is `{ id, label, price?, disabled?, cartParams? }`; 2+ entries show a "Select size" step. Selected size `id`/`price` override the slide and its `label` is appended to the title — same pattern as `variants`. * **cartParams** (optional, requires `enableAddToCart`): Extra string fields added to a configured add to cart request body, e.g. `{ "super_attribute[93]": "52" }`. Can be set on the slide, each variant and each size; they are layered, with size params overriding variant params, which override slide params. See [Add to Cart](https://docs.digitalgenius.com/docs/add-to-cart). ## Example Carousel Configuration with Variants: ```json { "type": "carousel", "slideOrientation": "horizontal", "carouselType": "product-carousel", "payload": [ { "id": 1, "trackingId": "apple", "image": "https://www.some-cdn/image1.jpg", "title": "Apple", "externalLink": "http://google.com", "price": "£10", "variants": [ { "id": 8, "image": "https://www.some-cdn/image1.jpg", // Required "name": "Red apple", "price": "£1", "externalLink": "http://google.com", "trackingId": "111" }, { "id": 9, "image": "https://www.some-cdn/image2.jpg", // Required "name": "Green apple", "price": "£2", "externalLink": "http://google.com", "trackingId": "222" } ] } ] } ``` ## Carousel Variant Properties: ```typescript { id: string | number; // Required image: string; // Required name?: string; // Optional price?: string; // Optional externalLink?: string; // Optional trackingId?: string; // Optional sizes?: CarouselSizeOption[]; // Optional — overrides slide sizes when this variant is selected cartParams?: Record; // Optional — layered over the slide's cartParams } ``` ## Example Carousel Configuration with Sizes (requires `enableAddToCart`): ```json { "type": "carousel", "slideOrientation": "horizontal", "carouselType": "product-carousel", "enableAddToCart": true, "payload": [ { "id": "runner-low", "trackingId": "runner-low", "image": "https://www.some-cdn/runner-low.jpg", "title": "Runner Low Trainer", "price": "£78", "sizes": [ { "id": "runner-low-uk5", "label": "5" }, { "id": "runner-low-uk6", "label": "6" }, { "id": "runner-low-uk7", "label": "7", "disabled": true }, { "id": "runner-low-uk8", "label": "8" } ] }, { "id": "belgravia-30", "trackingId": "belgravia-30", "image": "https://www.some-cdn/belgravia-30.jpg", "title": "Belgravia 30 Watch", "price": "£149", "sizes": [ { "id": "belgravia-30-standard", "label": "Standard" }, { "id": "belgravia-30-extended", "label": "Extended" } ] } ] } ``` ## Example Carousel Configuration with Sizes on Variants (requires `enableAddToCart`): ```json { "type": "carousel", "slideOrientation": "horizontal", "carouselType": "product-carousel", "enableAddToCart": true, "payload": [ { "id": "runner-low", "trackingId": "runner-low", "image": "https://www.some-cdn/runner-low-black.jpg", "title": "Runner Low Trainer", "price": "£78", "variants": [ { "id": "runner-low-black", "name": "Black", "image": "https://www.some-cdn/runner-low-black.jpg", "sizes": [ { "id": "runner-low-black-uk8", "label": "8" }, { "id": "runner-low-black-uk9", "label": "9" }, { "id": "runner-low-black-uk10", "label": "10", "disabled": true } ] }, { "id": "runner-low-white", "name": "White", "image": "https://www.some-cdn/runner-low-white.jpg", "sizes": [ { "id": "runner-low-white-uk8", "label": "8" }, { "id": "runner-low-white-uk9", "label": "9" } ] } ] } ] } ``` ## Carousel Size Properties: ```typescript { id: string | number; // Required — becomes item.id in onAddToCart label: string; // Required — shown on the chip, e.g. "M", "9", "Standard" price?: string; // Optional — overrides the slide price when this size is selected disabled?: boolean; // Optional — out of stock; shown, not selectable } ``` ## Sharing slides When `carouselType` is `product-recommendation`, each slide with an `http` or `https` `externalLink` shows a share button in the top right corner of its image. Tapping it opens the device's share sheet (the [Web Share API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/share)) with the slide's link, the product name as the share title and a short message from `lang.carouselShareText` as the text (default: `Thought you might like this: {productName}`, where `{productName}` is the slide's title). When a variant is selected, its `externalLink` is shared and the product name becomes `Title - Variant name` (using the variant's `title` if it has one). The button only appears in browsers that support Web Share, which requires the page to be served over HTTPS. Where it is unsupported the slide looks exactly as before. Sharing isn't tracked: it doesn't send a chat event, call `onCarouselSelection`, update the cart or send a selection to the flow. ## Callbacks for Carousel Events: **onCarouselDisplay**: Triggered when the carousel is displayed. The carouselType (if provided) is passed to the callback. ```javascript ``` **onCarouselSelection**: Triggered when a slide is selected. This callback receives the trackingId, slideData, carouselType, and carouselPayload as parameters. ```javascript ```