Carousel
Introduction
The Carousel component is a high-performance, native-scrolling slideshow that pages through a set of slides. Built specifically for CMS page building and zero-JS static rendering by default, it relies on modern CSS scroll-snap primitives rather than heavy JS transform logic.
As a result, touch swiping, trackpad scrolling, and keyboard arrow-key navigation work instantly even before client hydration. JavaSript is gracefully layered on only when indicators, prev/next buttons, and auto-play triggers are clicked.
Usage
You can configure and order slides, set display layouts, and control auto-play properties.
Basic Slideshow
A standard image banner featuring full-width slides with caption overlays and navigation links. Ideal for hero headers or main page showcases.
{
"blockType": "carousel",
"slides": [
{
"image": "https://images.unsplash.com/photo-1551288049-bebda4e38f71?w=800&q=80",
"caption": "Real-Time Analytics — Pulse delivers live data and dashboards with sub-second streaming latency.",
"href": "/features/analytics"
},
{
"image": "https://images.unsplash.com/photo-1518186285589-2f7649de83e0?w=800&q=80",
"caption": "AI-Powered Detection — Smart anomaly detection notifies your team before production breaks.",
"href": "/features/ai-detection"
},
{
"image": "https://images.unsplash.com/photo-1522071820081-009f0129c71c?w=800&q=80",
"caption": "Unified Team Workspaces — Share annotated charts and build custom workspaces with ease.",
"href": "/features/workspaces"
}
]
}
Autoplay Banner with Hover Controls
Configure the carousel to auto-advance at a set speed. To keep the interface accessible and non-intrusive, enable pauseOnHover so users can pause the playback simply by hovering over a slide.
{
"blockType": "carousel",
"loop": true,
"pauseOnHover": true,
"autoplayDelay": 3500,
"slides": [
{
"image": "https://images.unsplash.com/photo-1504384308090-c894fdcc538d?w=800&q=80",
"caption": "Developer Tools — Integrate your APIs in minutes with our native SDK wrappers.",
"href": "/developers"
},
{
"image": "https://images.unsplash.com/photo-1526374965328-7f61d4dc18c5?w=800&q=80",
"caption": "Ironclad Security — SOC2-compliant data storage and end-to-end encryption by default.",
"href": "/security"
}
]
}
Multi-Slide Layout
Display several slides side-by-side simultaneously. Excellent for product lists, team directories, and portfolio galleries. Set the slidesPerPage attribute along with custom spacing between the items.
{
"blockType": "carousel",
"slidesPerPage": 2,
"spacing": "16px",
"slides": [
{
"image": "https://images.unsplash.com/photo-1542744094-3a31f103e35f?w=400&q=80",
"caption": "Marketing Solutions",
"href": "/solutions/marketing"
},
{
"image": "https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=400&q=80",
"caption": "Financial Growth",
"href": "/solutions/financial"
},
{
"image": "https://images.unsplash.com/photo-1551836022-d5d88e9218df?w=400&q=80",
"caption": "HR Management",
"href": "/solutions/hr"
},
{
"image": "https://images.unsplash.com/photo-1507679799987-c73779587ccf?w=400&q=80",
"caption": "Executive Advisory",
"href": "/solutions/consulting"
}
]
}
Vertical Gallery Feed
Scroll through your slide content vertically instead of horizontally. Excellent for mobile-first content cards, media reels, or side navigation panels.
{
"blockType": "carousel",
"orientation": "vertical",
"slides": [
{
"image": "https://images.unsplash.com/photo-1517841905240-472988babdf9?w=800&q=80",
"caption": "Curated Feed — Category Spotlight"
},
{
"image": "https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=800&q=80",
"caption": "Trending Creator Profile"
},
{
"image": "https://images.unsplash.com/photo-1506794778202-cad84cf45f1d?w=800&q=80",
"caption": "Featured Technical Portfolio"
}
]
}
Accent-Themed with Overlaid Controls
Make the previous/next triggers and dots float on top of the images directly (instead of placing them underneath) using the inline property, and tint active visual cues with an accented colorPalette token.
{
"blockType": "carousel",
"inline": true,
"colorPalette": "purple",
"slides": [
{
"image": "https://images.unsplash.com/photo-1507238691740-187a5b1d37b8?w=800&q=80",
"caption": "Overlay Design Layout"
},
{
"image": "https://images.unsplash.com/photo-1531403009284-440f080d1e12?w=800&q=80",
"caption": "High Fidelity Previews"
}
]
}
Props
| Parameter | Type | Default | Description |
|---|---|---|---|
slides | List | - | An ordered collection of individual slides (see schema below). |
slidesPerPage | Number | 1 | Number of slides visible in the viewport simultaneously. |
spacing | String | - | CSS-compatible gap/space between visible slides (e.g., "16px", "1rem"). |
loop | Boolean | false | Whether the carousel wraps back around to the first slide upon reaching the end. |
autoplayDelay | Number | - | Auto-advance timer in milliseconds. Leave blank or omitted to disable autoplay entirely. |
pauseOnHover | Boolean | true | Pauses autoplay when the user hovers their pointer over the slides. |
orientation | Select | horizontal | Scrolling layout direction. Options: horizontal, vertical. |
inline | Boolean | false | Overlays navigation controllers and dots on top of the slide media rather than placing them in a container below. |
colorPalette | Select | - | Visual accent color for buttons and indicators. Options: blue, green, red, purple, orange, amber, cyan, slate. |
Slide Item Schema
Each entry in the slides parameter accepts the following properties:
| Property | Type | Required | Description |
|---|---|---|---|
image | Image | Yes | Path or URL to the background slide image. |
caption | String | No | Overlay description text rendered dynamically over the slide's lower region. |
href | String | No | Navigation URL or localised page route that the entire slide triggers upon click. |
Architecture Notes
- Zero Layout Shifts during SSR: To eliminate layout jumps during server rendering, the snap point markers and viewport widths are precalculated using a predictable structural formula matching the
slideCountandslidesPerPagesettings. - Robust Event Delegation: All click handlers for indicators, dot-pagination, and pause-triggers are managed via a single unified event listener delegated from the root container. This avoids assigning repetitive event listeners to static components inside the hydrated page template.
- CSS Scroll Snap: Pure CSS scroll-snapping handles layout alignment natively. On mobile touchscreens and modern trackpads, swipe-to-scroll transitions remain smooth and work correctly even when JavaScript is disabled or delayed.