feat: adding slides configuration in carousel

packages/pluggableWidgets/carousel-web/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Changed
+
+- We updated swiper library dependency to v14.2
+
+### Added
+
+- We added the option to configure number of slides per view (slides visible at the same time on slider's container) - contribution of @DiljohnSingh
+- We added the option to configure the numbers of slides for group sliding. Useful to use with slidesPerView > 1 - contribution of @DiljohnSingh.
+- When more than one slide is shown or grouped, slides now align to the start of the carousel and the fade animation is turned off, because it only supports one slide at a time.
+
+### Fixed
+
+- We fixed design preview not showing proper editable content height for widget dropzone area.
+
 ## [2.3.2] - 2026-04-13
 
 ### Changed

packages/pluggableWidgets/carousel-web/package.json

@@ -44,7 +44,7 @@
     "dependencies": {
         "@mendix/widget-plugin-component-kit": "workspace:*",
         "classnames": "^2.5.1",
-        "swiper": "^12.1.2"
+        "swiper": "^14.2.0"
     },
     "devDependencies": {
         "@mendix/automation-utils": "workspace:*",

packages/pluggableWidgets/carousel-web/src/Carousel.editorConfig.ts

@@ -21,6 +21,9 @@ export function getProperties(
     if (!values.autoplay) {
         hidePropertiesIn(defaultProperties, values, ["delay"]);
     }
+    if ((values.slidesPerView ?? 1) > 1 || (values.slidesPerGroup ?? 1) > 1) {
+        hidePropertiesIn(defaultProperties, values, ["animation"]);
+    }
     if (platform === "web") {
         transformGroupsIntoTabs(defaultProperties);
     }

packages/pluggableWidgets/carousel-web/src/Carousel.editorPreview.tsx

@@ -1,30 +1,49 @@
-import { GUID } from "mendix";
-import { ReactElement } from "react";
-import { generateUUID } from "@mendix/widget-plugin-platform/framework/generate-uuid";
+import classNames from "classnames";
+import { CSSProperties, ReactElement } from "react";
 import { CarouselPreviewProps } from "../typings/CarouselProps";
-import { Carousel } from "./components/Carousel";
 
 export function getPreviewCss(): string {
-    return require("./ui/Carousel.scss");
+    return require("./ui/CarouselPreview.scss");
 }
 
+// Static preview: Swiper needs a live DOM to initialize, which the Studio Pro page editor does not provide.
 export function CarouselPreviewComponent(props: CarouselPreviewProps): ReactElement {
+    const hasDataSource = props.dataSource != null;
+    const slidesPerView = Math.max(1, props.slidesPerView ?? 1);
+    const slides = Array.from({ length: slidesPerView }, (_, index) => index);
+
     return (
-        <Carousel
-            id={generateUUID().toString()}
-            className={props.className}
-            navigation={props.navigation}
-            pagination={props.showPagination}
-            loop={false}
-            items={["1", "2", "3"].map(item => ({
-                id: item as GUID,
-                content: (
-                    <props.content.renderer caption={`Carousel item content ${item}`}>
-                        <div>{`Carousel item content ${item}`}</div>
-                    </props.content.renderer>
-                )
-            }))}
-        />
+        <div
+            className={classNames(props.className, "widget-carousel", "widget-carousel-editor-preview")}
+            style={{ "--carousel-preview-slides-per-view": slidesPerView } as CSSProperties}
+        >
+            <div className="widget-carousel-preview-viewport">
+                {props.navigation && <span className="widget-carousel-preview-nav widget-carousel-preview-prev" />}
+                <ul className="widget-carousel-preview-slides">
+                    {slides.map(index => (
+                        <li key={index} className="widget-carousel-preview-slide">
+                            {hasDataSource ? (
+                                <props.content.renderer>
+                                    <div className="carousel-item-content" />
+                                </props.content.renderer>
+                            ) : (
+                                <div className="carousel-item-content">
+                                    <div className="carousel-item-content-text">[No datasource selected]</div>
+                                </div>
+                            )}
+                        </li>
+                    ))}
+                </ul>
+                {props.navigation && <span className="widget-carousel-preview-nav widget-carousel-preview-next" />}
+            </div>
+            {props.showPagination && (
+                <div className="widget-carousel-preview-pagination">
+                    <span className="widget-carousel-preview-bullet widget-carousel-preview-bullet-active" />
+                    <span className="widget-carousel-preview-bullet" />
+                    <span className="widget-carousel-preview-bullet" />
+                </div>
+            )}
+        </div>
     );
 }
 

packages/pluggableWidgets/carousel-web/src/Carousel.tsx

@@ -1,18 +1,40 @@
 import classNames from "classnames";
 import { GUID, ObjectItem, ValueStatus } from "mendix";
-import { ReactNode, useCallback, useId } from "react";
+import { ReactNode, useCallback, useId, useMemo } from "react";
 import { executeAction } from "@mendix/widget-plugin-platform/framework/execute-action";
 import { CarouselContainerProps } from "../typings/CarouselProps";
 import { Carousel as CarouselComponent } from "./components/Carousel";
-import "./ui/Carousel.scss";
+
 import loadingCircleSvg from "./ui/loading-circle.svg";
 
+import "./ui/Carousel.scss";
+
 export function Carousel(props: CarouselContainerProps): ReactNode {
-    const { showPagination, loop, tabIndex, navigation, animation, delay, autoplay } = props;
+    const {
+        showPagination,
+        loop,
+        tabIndex,
+        navigation,
+        animation,
+        delay,
+        autoplay,
+        slidesPerView,
+        slidesPerGroup,
+        dataSource,
+        content
+    } = props;
     const onClick = useCallback(() => executeAction(props.onClickAction), [props.onClickAction]);
     const id = useId();
+    const carouselItems = useMemo(
+        () =>
+            dataSource?.items?.map((item: ObjectItem) => ({
+                id: item.id as GUID,
+                content: content?.get(item)
+            })) ?? [],
+        [dataSource]
+    );
 
-    if (props.dataSource?.status !== ValueStatus.Available) {
+    if (dataSource?.status !== ValueStatus.Available) {
         return (
             <div className={classNames(props.class, "widget-carousel")} tabIndex={tabIndex}>
                 <img src={loadingCircleSvg} className="widget-carousel-loading-spinner" alt="" aria-hidden />
@@ -27,16 +49,13 @@ export function Carousel(props: CarouselContainerProps): ReactNode {
             tabIndex={tabIndex}
             pagination={showPagination}
             loop={loop}
+            slidesPerView={slidesPerView}
+            slidesPerGroup={slidesPerGroup}
             animation={animation}
             autoplay={autoplay}
             delay={delay}
             navigation={navigation}
-            items={
-                props.dataSource?.items?.map((item: ObjectItem) => ({
-                    id: item.id as GUID,
-                    content: props.content?.get(item)
-                })) ?? []
-            }
+            items={carouselItems}
             onClick={onClick}
         />
     );

packages/pluggableWidgets/carousel-web/src/Carousel.xml

@@ -37,6 +37,14 @@
                     <caption>Infinite loop</caption>
                     <description />
                 </property>
+                <property key="slidesPerView" type="integer" defaultValue="1">
+                    <caption>Slides per view</caption>
+                    <description />
+                </property>
+                <property key="slidesPerGroup" type="integer" defaultValue="1">
+                    <caption>Slides per group</caption>
+                    <description />
+                </property>
                 <property key="animation" type="boolean" defaultValue="true">
                     <caption>Animation</caption>
                     <description />

packages/pluggableWidgets/carousel-web/src/__tests__/Carousel.editorPreview.spec.tsx

@@ -0,0 +1,52 @@
+import { render } from "@testing-library/react";
+import { ReactNode } from "react";
+import { CarouselPreviewProps } from "../../typings/CarouselProps";
+import { CarouselPreviewComponent } from "../Carousel.editorPreview";
+
+const renderer = ({ children }: { children: ReactNode }): ReactNode => children;
+
+const defaultProps = {
+    className: "",
+    dataSource: {},
+    content: { renderer },
+    showPagination: true,
+    navigation: true,
+    autoplay: false,
+    delay: 1000,
+    loop: true,
+    slidesPerView: 1,
+    slidesPerGroup: 1,
+    animation: true,
+    onClickAction: null
+} as unknown as CarouselPreviewProps;
+
+describe("Carousel preview", () => {
+    it.each([1, 3, 10])("renders %i slides for slidesPerView %i", slidesPerView => {
+        const { container } = render(<CarouselPreviewComponent {...defaultProps} slidesPerView={slidesPerView} />);
+
+        expect(container.querySelectorAll(".widget-carousel-preview-slide")).toHaveLength(slidesPerView);
+    });
+
+    it("falls back to a single slide when slidesPerView is empty or invalid", () => {
+        const { container, rerender } = render(<CarouselPreviewComponent {...defaultProps} slidesPerView={null} />);
+        expect(container.querySelectorAll(".widget-carousel-preview-slide")).toHaveLength(1);
+
+        rerender(<CarouselPreviewComponent {...defaultProps} slidesPerView={0} />);
+        expect(container.querySelectorAll(".widget-carousel-preview-slide")).toHaveLength(1);
+    });
+
+    it("shows a placeholder when no datasource is selected", () => {
+        const { getAllByText } = render(<CarouselPreviewComponent {...defaultProps} dataSource={null} />);
+
+        expect(getAllByText("[No datasource selected]")).toHaveLength(1);
+    });
+
+    it("hides navigation and pagination when disabled", () => {
+        const { container } = render(
+            <CarouselPreviewComponent {...defaultProps} navigation={false} showPagination={false} />
+        );
+
+        expect(container.querySelector(".widget-carousel-preview-nav")).toBeNull();
+        expect(container.querySelector(".widget-carousel-preview-pagination")).toBeNull();
+    });
+});

packages/pluggableWidgets/carousel-web/src/components/Carousel.tsx

@@ -19,6 +19,8 @@ export interface CarouselProps {
     animation?: boolean;
     autoplay?: boolean;
     delay?: number;
+    slidesPerView?: number;
+    slidesPerGroup?: number;
     navigation: boolean;
     className: string;
     tabIndex?: number | undefined;
@@ -27,7 +29,21 @@ export interface CarouselProps {
 }
 
 export function Carousel(props: CarouselProps): ReactElement {
-    const { items, pagination, loop, animation, autoplay, delay, navigation, className, tabIndex, id, onClick } = props;
+    const {
+        items,
+        pagination,
+        loop,
+        animation,
+        autoplay,
+        delay,
+        slidesPerView,
+        slidesPerGroup,
+        navigation,
+        className,
+        tabIndex,
+        id,
+        onClick
+    } = props;
     const [activeIndex, setActiveIndex] = useState<number>(0);
 
     const getSlideId = useCallback(
@@ -46,17 +62,24 @@ export function Carousel(props: CarouselProps): ReactElement {
             )}" aria-label="Go to slide ${index}" class="${className}"></span>`
     };
 
+    const perView = Math.max(1, slidesPerView ?? 1);
+    const perGroup = Math.max(1, slidesPerGroup ?? 1);
+    // Swiper's fade effect forces a single slide per view/group, so only use it for single-slide carousels.
+    const isSingleSlide = perView === 1 && perGroup === 1;
+
     const options: SwiperOptions = {
-        slidesPerView: 1,
-        centeredSlides: true,
+        slidesPerView: perView,
+        slidesPerGroup: perGroup,
+        centeredSlides: isSingleSlide,
         loop,
         navigation,
         autoplay: autoplay ? { delay, stopOnLastSlide: true } : false,
         pagination: paginationOptions,
-        ...(animation && {
-            effect: "fade",
-            fadeEffect: { crossFade: true }
-        }),
+        ...(animation &&
+            isSingleSlide && {
+                effect: "fade",
+                fadeEffect: { crossFade: true }
+            }),
         modules: [A11y, Navigation, Pagination, EffectFade, Autoplay, Keyboard],
         a11y: {
             enabled: true,
@@ -67,6 +90,8 @@ export function Carousel(props: CarouselProps): ReactElement {
         }
     };
 
+    const isSlideVisible = (index: number): boolean => (index - activeIndex + items.length) % items.length < perView;
+
     const updateSwiperIndex = useCallback((swiper: SwiperClass) => {
         setActiveIndex(swiper.realIndex);
     }, []);
@@ -76,12 +101,12 @@ export function Carousel(props: CarouselProps): ReactElement {
             <Swiper
                 onActiveIndexChange={updateSwiperIndex}
                 wrapperTag={"ul"}
-                {...options}
                 onClick={onClick}
                 onSwiper={updateSwiperIndex}
+                {...options}
             >
                 {items?.map((item, index) => (
-                    <SwiperSlide tag={"li"} aria-hidden={index !== activeIndex} key={item.id} id={getSlideId(item)}>
+                    <SwiperSlide tag={"li"} aria-hidden={!isSlideVisible(index)} key={item.id} id={getSlideId(item)}>
                         {item.content}
                     </SwiperSlide>
                 ))}

packages/pluggableWidgets/carousel-web/src/components/__tests__/Carousel.spec.tsx

@@ -156,13 +156,16 @@ describe("Carousel", () => {
         jest.resetAllMocks();
         jest.spyOn(Math, "random").mockReturnValue(0.123456789);
     });
+
     const defaultCarouselProps: CarouselProps = {
         id: "Carousel",
         className: "",
         items: [
             { id: "1" as GUID, content: <div>test1</div> },
             { id: "2" as GUID, content: <div>test2</div> }
         ],
+        slidesPerView: 1,
+        slidesPerGroup: 1,
         pagination: true,
         animation: true,
         autoplay: true,
@@ -177,21 +180,40 @@ describe("Carousel", () => {
 
         expect(asFragment()).toMatchSnapshot();
     });
+
     it("renders correctly without pagination", () => {
         const { asFragment } = render(<Carousel {...defaultCarouselProps} pagination={false} />);
 
         expect(asFragment()).toMatchSnapshot();
     });
+
     it("renders correctly without navigation", () => {
         const { asFragment } = render(<Carousel {...defaultCarouselProps} navigation={false} />);
 
         expect(asFragment()).toMatchSnapshot();
     });
+
     it("renders correctly with minimal setup", () => {
         const { asFragment } = render(<Carousel {...defaultCarouselProps} pagination={false} navigation={false} />);
 
         expect(asFragment()).toMatchSnapshot();
     });
+
+    it("uses fade effect for a single slide per view", () => {
+        const { container } = render(<Carousel {...defaultCarouselProps} />);
+
+        expect(container.querySelector(".swiper")).toHaveClass("swiper-fade");
+    });
+
+    it("ignores fade animation when showing multiple slides per view", () => {
+        const items = [1, 2, 3, 4].map(i => ({ id: `${i}` as GUID, content: <div>test{i}</div> }));
+        const { container } = render(
+            <Carousel {...defaultCarouselProps} items={items} slidesPerView={2} slidesPerGroup={2} />
+        );
+
+        expect(container.querySelector(".swiper")).not.toHaveClass("swiper-fade");
+    });
+
     afterEach(() => {
         jest.restoreAllMocks();
     });

packages/pluggableWidgets/carousel-web/src/ui/Carousel.scss

@@ -64,3 +64,7 @@ $focus-outline-offset: 2px !default;
         transform: rotate(360deg);
     }
 }
+
+ul.swiper-wrapper {
+    padding-inline-start: 0;
+}