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. Currently the only supported type is product-carousel
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), 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.

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`):

{
  "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`):

{
  "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
}

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 4 days ago

Did this page help you?