The Image Carousel display format renders an ACF Gallery field’s images inside a swipeable Swiper.js carousel. Two motion modes are available — discrete “Slide” advances and a continuous “Scroll” marquee — and an optional lightbox or full-size view on click.
The format is well-suited to hero sliders, logo strips, and any image collection that benefits from autoplay or paged navigation.
Supported Field Types
The Image Carousel display format supports the following field types:
- Gallery
Customization
Sidebar controls cover the visible image count per slide, the click behavior, the per-tile aspect ratio and scale, image spacing, and a dedicated Slider Settings panel for autoplay and motion options.
| Customization | Description | Note |
|---|---|---|
| Images per slide | Number of images visible at once per breakpoint (desktop / tablet / mobile). Range: 1–8. | |
| On click action | What happens when a visitor clicks an image. Options: Do nothing, View in lightbox, View full size on same tab, View full size on new tab. | |
| Effect | Carousel motion. Options: Slide (discrete page advances), Scroll (continuous marquee). | |
| Direction | Travel direction. Options: To Left, To Right. | |
| Slide Interval | Seconds between automatic advances. Range: 0.5–10, step 0.5. | Only shown when Effect is “Slide”. |
| Scrolling Speed | Speed of the continuous marquee. Range: 0.5–10, step 0.5 (higher value = faster scroll). | Only shown when Effect is “Scroll”. |
| Images to slide | Number of images advanced per autoplay tick or swipe. Bounded by the current Images per slide. | Lives in the Slider Settings panel, with a per-breakpoint responsive control. Only shown when Effect is “Slide”. |
| Pause on Hover | Pauses autoplay while the visitor’s cursor is over the carousel. | Only shown when Effect is “Slide” (front-end only). |
| Image spacing | Pixel gap between adjacent slides. Range: 0–100. | |
| Aspect Ratio | Fixed ratio every slide crops to. | |
| Scale | How each image fits its slide. Options: Cover, Contain, Fill. | Only available when a non-“Original” Aspect Ratio is set. |
| Resolution | Which registered image size is loaded as the src. | |
| Empty Message | Toggle (“Show message if empty”) plus fallback text shown when the gallery has no images. | |
| Layout Variations | Switch the variation to render the same gallery as a grid or masonry layout instead of a carousel. | The Grid / Carousel / Masonry variations share the same underlying block — switching only changes the type attribute. |
The block also supports the following standard WordPress block controls: Block Alignment (wide, full), Border (color, width, radius applied to each slide’s <img>), Margin, Padding, and a Duotone Filter applied to every image.