The Complete Guide to Groundworx Carousel Block

Master the responsive carousel block that gives you complete control over your WordPress content displays

Getting Started

The Groundworx Carousel Block transforms any WordPress content into beautiful, responsive carousels. Built with Embla Carousel and the WordPress Interactivity API, it offers professional templates and granular responsive control — all within the native block editor.

What You’ll Learn

By the end of this guide, you’ll know how to:

Set up and configure a carousel with any content
Choose and customize from 9 professional templates
Control carousel behavior across 6 responsive breakpoints
Style arrows and pagination using theme.json button styles
Disable the carousel at specific breakpoints for a grid layout
Create custom block variations for your team
Add your own reusable templates

Prerequisites

WordPress 6.5 or higher
PHP 8.2 or higher
A block theme (recommended) or classic theme with Gutenberg support
Basic understanding of the WordPress block editor

Basic Setup & Configuration

Installing the Plugin

Via WordPress Admin:

Navigate to Plugins → Add New
Search for “Groundworx Carousel”
Click Install Now, then Activate

Manual Installation:

Download the plugin from WordPress.org
Upload via Plugins → Add New → Upload Plugin
Activate the plugin

Creating Your First Carousel

Step 1: Add the Carousel Block

Create or edit a post/page
Click the + icon to insert a block
Search for “Carousel” or browse to Design → Carousel
Insert the block

Step 2: Add Slides

The carousel starts with one empty slide. To add more:

Click Add Slide in the block toolbar (on the Carousel or any Slide)
The Carousel’s “Add Slide” button appends to the end; the Slide’s button inserts after the current slide

Step 3: Add Content to Slides

Each slide is a flex container that accepts any WordPress block — images, text, buttons, groups, covers, custom blocks, or anything else.

The Layout Panel

The Layout panel in the block sidebar contains the top-level settings that apply to the entire carousel.

Template

Choose from 9 layout templates that control how arrows, pagination, viewport, and progress bar are arranged. See the Templates section below for details and live examples.

Arrow Style

Choose from 11 arrow icon designs. Default: Chevron.

Pagination Style

Choose from 9 pagination indicator designs. Default: Circle Outline. The Number style displays slide numbers (1, 2, 3…) and supports background and border color customization.

Disable Carousel At

Convert the carousel to a CSS grid layout starting at a specific breakpoint. Once disabled, the carousel stays as a grid at all larger breakpoints. Options: Never, Large Phone, Tablet, Laptop, Desktop, Large Desktop.

Responsive Breakpoint Settings

Below the Layout panel, tabbed controls let you configure carousel behavior independently at each screen size. Settings follow a mobile-first approach — they cascade from smaller to larger breakpoints unless overridden.

Breakpoints

The carousel uses 6 breakpoint levels:

Default (Mobile) — 0px (base styles)
Large Phone — 480px and up
Tablet — 680px and up
Laptop — 1080px and up
Desktop — 1280px and up
Large Desktop — 1440px and up

Carousel Mode Controls (per breakpoint)

When a breakpoint is in carousel mode (not destroyed), these controls are available:

Type — Slide (standard horizontal sliding) or Loop (infinite continuous scrolling)
Slides Justification (Loop mode only) — Start, Center, or End alignment
Carousel Item Size — Per Page (number of visible slides, 1–10) or Fixed Width (explicit width like “300px”). Selecting one clears the other.
Slides Per Move — How many slides to scroll per action (1–10)
Contain Scroll — When enabled (default), trims empty snap points at the end of the carousel
Autoplay — Automatically advance slides every 4 seconds. Pauses on hover.
Pagination — Show/hide pagination indicators
Arrows — Show/hide navigation arrows
Progress Bar — Show/hide a horizontal progress indicator
Counter — Show/hide a slide counter (e.g., “3 / 10”) between the arrows

Grid Mode Controls (per breakpoint)

When the carousel is destroyed at a breakpoint, these controls replace the carousel settings:

Grid Layout — Column Count (fixed number, 1–10) or Minimum Column Width (responsive auto-fill, e.g., “300px”)
Equal Row Height — When enabled, all grid rows have equal height. This value cascades from the first destroyed breakpoint.

Navigation Styles

The carousel offers 11 arrow styles and 9 pagination styles. Here are live examples showing different combinations:

Arrow & Pagination Style Examples

Chevron arrows + Circle Outline pagination (defaults)

Arrow arrows + Square Outline pagination

Half Arrow arrows + Diamond Outline pagination

Play arrows + Rectangle pagination

Play Rounded arrows + Number pagination

Thin Chevron arrows + Circle pagination

Triangle arrows + Diamond pagination

Templates

Version 3.0 includes 9 template variations that control the positioning of arrows, pagination, viewport, and progress bar using CSS Grid layouts:

Default — Arrows flanking the viewport

Default Alt — Arrows flanking with outset pagination

Simple — Arrows positioned center

Simple Left — Arrows positioned left

Simple Right — Arrows positioned right

Overlay — Arrows overlaying the viewport

Overlay Alt — Arrows overlaying with outset pagination

Partial Overlay — Arrows partially overlaying the viewport

Partial Overlay Alt — Partial overlay with outset pagination

Colors

The carousel uses a layered color system that integrates with your WordPress theme.

Default Colors (Theme Integration)

Out of the box, carousel UI elements inherit colors from your theme:

Arrows and Number Pagination use the wp-element-button class. Their default text, background, and border colors come from your theme’s button element styles in theme.json. If your theme defines button colors, these elements match automatically.
Non-number Pagination and Counter inherit the carousel block’s text color. Set the text color on the carousel block itself, and these elements follow.
Progress Bar has no default color — set it explicitly using the color controls below.

Color Overrides (Inspector Panel)

Override the theme defaults for any UI element using the color controls in the block sidebar (under the Color group). All controls support both theme preset colors and custom colors.

Arrow Colors:

Text — Arrow icon color
Background — Arrow button background
Border — Arrow button border

Pagination Colors:

For non-number styles (circle, square, diamond, rectangle):

Active Pagination — Text color for the active indicator
Inactive Pagination — Text color for inactive indicators

For the Number pagination style:

Active Pagination — Text, Background, and Border colors
Inactive Pagination — Text, Background, and Border colors

Progress Bar Colors:

Foreground — The progress indicator bar
Background — The track behind the bar

Counter Color:

Text — The counter text color

The Slide Block

Each slide within the carousel is its own block with a few settings:

Minimum Height — Set a min-height value (e.g., 300px, 20rem) in the Dimensions panel
Color — Text and background colors with gradient support
Spacing — Padding and block gap
Layout — Content sizing and alignment options

The Slide toolbar includes an Add Slide button that inserts a new slide immediately after the current one.

Block Supports

The Carousel block supports the following WordPress block features:

Alignment — Full width and wide width
Color — Text color (cascades to pagination and counter), background color, gradients
Typography — Font size, line height, font family, weight, style, text transform, text decoration, letter spacing
Spacing — Padding (all sides), margin (top and bottom), block gap (controls gap between slides)
Border — Border color, radius, style, and width
Shadow — Box shadow support
Layout — Default layout with justification and orientation controls

Accessibility

The carousel follows WCAG 2.1 AA accessibility best practices:

The carousel wrapper uses role="region" with aria-roledescription="carousel"
Each slide has role="tabpanel" with aria-roledescription="slide"
Pagination uses the tablist/tab pattern with proper ARIA roles
Arrow keys (Left/Right) and Home/End navigate between pagination dots
Arrow buttons have descriptive labels (“Previous slide” / “Next slide”)
The counter uses aria-live="polite" for slide change announcements
Off-screen slides receive the inert attribute and aria-hidden="true", preventing keyboard focus from entering hidden slides
Full touch/swipe gesture support for mobile devices

Developer Guide

Block Variations

wp.blocks.registerBlockVariation( 'groundworx/carousel', {
    name: 'testimonial-carousel',
    title: 'Testimonial Carousel',
    attributes: {
        template: 'simple',
        carouselOptions: {
            type: 'loop',
            perPage: 1,
            arrows: true,
            pagination: true,
            autoplay: true,
            containScroll: 'trimSnaps',
        },
    },
    scope: [ 'block', 'inserter', 'transform' ],
} );

Custom Templates

Add custom templates via the groundworx.carousel.templates filter:

wp.hooks.addFilter(
    'groundworx.carousel.templates',
    'my-theme/custom-template',
    ( templates ) => [
        ...templates,
        { label: 'My Custom Template', value: 'my-custom' },
    ]
);

Then style it in your theme CSS using the .template-my-custom class on the carousel root element.

Carousel Options Reference

The carouselOptions attribute accepts the following options:

type — "slide" or "loop" (default: "slide")
align — "start", "center", or "end" (default: "start")
perPage — Number of slides per page, 1–10 (default: 1)
fixedWidth — Fixed slide width (e.g., "300px")
slidesToScroll — Slides to scroll per action (default: 1)
gap — Gap between slides (synced from block gap setting)
containScroll — "trimSnaps" or false (default: "trimSnaps")
autoplay — Enable autoplay (default: false)
arrows — Show arrow navigation (default: true)
pagination — Show pagination dots (default: false)
progressBar — Show progress bar (default: false)
counter — Show slide counter (default: false)
destroy — Disable carousel for grid mode (default: false)
breakpoints — Object with per-breakpoint overrides using the same options

Migration from v2.x

Version 3.0 migrated from Splide.js to Embla Carousel. Existing blocks with splideOptions are automatically migrated to carouselOptions when opened in the editor. Blocks that haven’t been re-saved continue to render correctly via a PHP fallback.

Key renames:

perMove → slidesToScroll
omitEnd → containScroll
focus: "center" → align: "center"

Removed in v3.0:

Fade transition type (use Groundworx Showcase for fade, auto-scroll, and vertical slides)
Rewind option (use Loop mode instead)
Auto Height option
Custom interval and speed settings (autoplay uses a fixed 4-second interval)
Phone and Large Tablet breakpoints (streamlined from 7 to 5 breakpoints)

Need More? Check Out Groundworx Showcase

Groundworx Carousel is a self-contained carousel block — you add slides manually, and navigation (arrows, pagination, etc.) is built into the block itself. It’s a great fit for static content like testimonials, feature highlights, or image galleries where you control every slide.

Groundworx Showcase takes a fundamentally different approach: a modular block system where every piece — the carousel, the slides, and each navigation control — is its own independent block. 12 blocks, 4 flow types, and full query support.

Showcase adds:

Query-driven carousels — Pull slides automatically from posts, pages, custom post types, or WooCommerce products
Block pattern support — Design a slide layout once, every queried post fills that pattern
Independent navigation blocks — Arrows, pagination, progress bar, and counter are separate blocks you can place anywhere
More modes — Fade transitions, vertical slides, auto-scroll, and RTL text direction
Per-breakpoint layout switching — Switch between carousel, grid, and flex at every breakpoint independently

Learn more about Groundworx Showcase →

Tutorial