Carousel Kit: A Composable Carousel System with the WordPress Interactivity API

The WordPress Block Editor has fundamentally changed how we build component-based publishing experiences. However, modern WordPress has ingredients many in the ecosystem need to utilize fully. 

Even now, most complex blocks are built as monolithic units where logic and UI are trapped in a single, rigid component. To solve this, we built Carousel Kit: a production-ready carousel and slider system designed as a reference implementation for the WordPress Interactivity API (IAPI).

It is a high-performance, composable system that treats interactivity as a shared protocol. By establishing a shared architectural scope, it allows independent UI elements—like navigation arrows, dots, and slide counters—to communicate seamlessly, regardless of how they are nested within a layout.

Key Features

Built to solve the rigidity of traditional Gutenberg sliders, Carousel Kit uses the Interactivity API to manage the relationship between independent blocks, allowing for a level of design flexibility that monolithic sliders cannot match:

• Standardized State Sync: Uses the WordPress Interactivity API (IAPI) to keep independent UI blocks (like arrows and pagination) in sync with the slider.
• Embla Integration: Leverages Embla Carousel to handle scrolling and accessibility logic, keeping the JavaScript footprint 85% smaller than alternatives.
• Modular Sub-Blocks: Provides separate blocks for the Viewport, Navigation, and Pagination that can be arranged anywhere within the parent container’s scope.
• Dynamic Query Support: Built to work natively with the Query Loop block, turning any post collection into a performant slider without manual configuration.

Better Interaction to Next Paint (INP): By replacing heavy, “all-in-one” libraries with fine-grained signals, the browser spends significantly less time on scripting tasks during user interaction.

The Problem: Rigid UI vs. Design Freedom

Traditionally, building a slider requires packaging everything—the logic, the arrows, the slides—into one monolithic block. This creates Component State Isolation. If an editor wants to move the navigation “dots” into a separate column or place a heading between the arrows and the viewport, the connection breaks. You are forced to choose between a functional slider or a bespoke design.

Carousel Kit solves this through Composable Block System & Shared States.

The Advantage? You can nest navigation controls inside columns, group blocks, or sidebars. You can have a “Next” button at the bottom of a long page section and the slides at the top. This provides total layout freedom without writing a single line of custom JavaScript to reconnect the UI.

Why the Interactivity API?

The decision to adopt the IAPI was a strategic choice for long-term scalability. In the past, developers had to choose between heavy React-based hydration on the frontend or brittle, imperative Vanilla JS.The IAPI offers a third way: Standardized, Declarative State.

By using Preact Signals under the hood, the IAPI allows us to define the logic of our carousel once and let the native WordPress runtime handle the surgical DOM updates. It moves the industry away from “spaghetti” event listeners toward a “Single Source of Truth.”

The Compound Block Pattern: A Strategy for Scalability

Beyond raw speed, the “Islands of Interactivity” problem is solved through composability. We architected this system as a suite of atomic sub-blocks: Parent, Viewport, Slide, and Controls providing two distinct advantages for enterprise environments:

Decoupling Logic from UI

In a traditional carousel, navigation elements are hardcoded into the container. In our system, these are independent blocks that “subscribe” to a shared data store. This allows editors to place navigation elements anywhere within a layout without breaking functional logic.

Extensibility Without Modification

Because the system exposes its internal state (index, autoplay status, etc.) via a shared context, it becomes an open ecosystem. Any developer can build a separate block, a progress bar or a slide counter that interacts with the carousel without modifying the original plugin’s code.

Empirical Results: Performance as a Structural Requirement

With Interactivity API, we successfully demonstrate that performance can now be an inherent property of the architecture itself. 

To validate this, we stress-tested Carousel Kit against leading traditional Gutenberg slider blocks on a Twenty Twenty-Five theme with 10 carousels per page, under 4x CPU throttling to simulate real-world mobile environments.

The benchmarks tell a clear story: modern engineering is as much about what you don’t load as what you do.

• Main-Thread Efficiency: With a Processing Duration of just 1ms, the system eliminates “jank,” ensuring the page remains responsive even under heavy load.
• Superior Interaction to Next Paint (INP): Leveraging fine-grained Signals resulted in a 31% improvement in INP. This ensures the interface feels instantaneous, directly benefiting site SEO and Google Core Web Vitals.
• Dead Code/Bundle Size: Traditional plugins bundle massive libraries like Swiper.js. Carousel Kit reduces the total bundle size by nearly 85%. The “unused” code in legacy plugins is often 5x larger than our entire functional script.

Editorial Experience: Modularity Over Monoliths

While the architecture is driven by engineering standards & performance, the practical result is a more intuitive editorial experience. By replacing the traditional “mega-sidebar” of settings with a modular building experience, editors gain granular control directly within the canvas:

Content Agnostic Slides

Each slide is a nested block container. Users can mix static content like images and video with dynamic sources like the Query Loop block.

Decoupled UI

Navigation elements (Dots, Controls) are independent blocks. This allows for non-traditional layouts—such as placing pagination above the viewport—without custom CSS.

Constraint-Based Editing

For enterprise governance, developers can use “Allowed Blocks” to restrict what can be placed within a slider, ensuring design consistency across high-scale sites.

Extensibility: A Real-World Example

The true strength of this system lies in its ability to act as a data foundation for the rest of the page. Because the IAPI broadcasts state within its scope, a developer can create completely independent blocks that “subscribe” to the carousel’s internal logic without writing new event listeners.

For example, a progress bar tracking an autoplay timer can be implemented with simple declarative attributes:

<div data-wp-interactive="rt-blocks/carousel" class="carousel-progress">
  <div
    class="carousel-progress__bar"
    data-wp-bind--key="context.timerIterationId"
    data-wp-class--is-playing="context.isPlaying"
    data-wp-bind--style="state.progressDuration"
  ></div>
</div>

Result

This is the Composable Block System in practice: providing a data foundation for an infinite variety of UI expressions without direct code dependencies or monolithic constraints.

Building for the Long Term

Carousel Kit is a production-grade implementation of the Interactivity API.

By using the IAPI, we aim to move towards an ecosystem where blocks are no longer isolated silos, but participants in a fast, native framework. We’ve open-sourced this kit to show how these modular principles can be applied to complex projects today. 

We invite the community and enterprises building with WordPress to explore what modern WordPress has to offer and build future-forward solutions with Interactivity API, Block Bindings API, Abilities API, and more. 

We look forward to your feedback and contributions to Carousel Kit on GitHub.

Links

• Source Code: GitHub Repository
• Implementation Specs: API Documentation
• Live Demo: Explore on WordPress Playground