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. Aproduct-recommendationcarousel also shows a share button on each slide that has anexternalLink(see 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 configuredecomPlatformandcartrequest; see 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 sizeid/priceoverride the slide and itslabelis appended to the title — same pattern asvariants. - 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.
Example Carousel Configuration with Variants:
{
"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:
{
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<string, string>; // Optional — layered over the slide's cartParams
}Example Carousel Configuration with Sizes (requires enableAddToCart):
enableAddToCart):{
"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):
enableAddToCart):{
"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:
{
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) 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.
<script>
window.DG_CHAT_WIDGET_CONFIG = {
callbacks: {
onCarouselDisplay: (carouselType) => {
console.log(carouselType);
}
}
}
</script>onCarouselSelection: Triggered when a slide is selected. This callback receives the trackingId, slideData, carouselType, and carouselPayload as parameters.
<script>
window.DG_CHAT_WIDGET_CONFIG = {
callbacks: {
onCarouselSelection: (trackingId, slideData, carouselType, carouselPayload) => {
console.log(trackingId, slideData, carouselType, carouselPayload);
}
}
}
</script>Updated 3 days ago
Did this page help you?