RFC-011: Carousel Plugin

[floor]

RFC-011: Carousel Plugin

Status: Draft
Author: floor
Type: Plugin / Feature
Created: 2026-06-06

---

Summary

Add a carousel() plugin that provides true infinite-loop scrolling for carousel and wizard UIs. Instead of the current scroll.wrap behavior (which scrolls backward through the entire list to wrap around), the carousel plugin scrolls forward seamlessly — item N is followed by item 0 as if the list were circular.

const list = createVList({
  container: "#app",
  items: slides,
  item: { height: 400, template: renderSlide },
}, [carousel()]);

---

Motivation

The current scroll.wrap config in the core handles index wrapping in scrollToIndex, but the scroll animation rewinds through all items to reach the other end. For a 16-item wizard, pressing "next" on the last card scrolls backward past 15 cards to reach card 0. This feels broken for carousel UIs where the user expects continuous forward motion.

Real-world carousel patterns (image galleries, onboarding wizards, plugin explorers, testimonial sliders) all require the illusion of an infinite loop — the content wraps but the scroll always moves in the user's direction.

---

Design

Core principle

The scroll position is unbounded — it can grow past totalSize or go negative. The render pipeline maps indices via modulo:

visibleIndex = ((scrollIndex % total) + total) % total

Items are positioned relative to the viewport using their modulo'd index. No item duplication — the same item pool is reused, just with wrapped indices.

Plugin responsibilities

Responsibility	Approach
Unbounded scroll	Override scroll setter to allow positions beyond [0, totalSize]
Index modulo	Override getItemFn to wrap indices: items[index % total]
Content size	Set content size to a large virtual range (e.g. totalSize * 1000) so native scrollbar has room
scrollToIndex	Override to compute the shortest-path scroll target: forward or backward, whichever is closer
Snap-to-item	Optional: snap to the nearest item boundary on scroll idle
Keyboard	ArrowDown/Right always moves forward, ArrowUp/Left always moves backward — never jumps across the entire list

Layout variants (MD3-inspired)

The plugin supports four layout modes aligned with Material Design 3 Carousel:

Variant	Description	Use case
"full"	One item fills the viewport. Swipe/button to advance.	Wizards, onboarding, full-screen galleries
"hero"	One large focal item with small peek items on each side. Focal item scales up, adjacent items scale down.	Featured content, product highlights
"multi"	Multiple items visible at once. The focal item is slightly larger, adjacent items peek from the edges.	Image galleries, card carousels
"free"	Items scroll freely without snapping. No focal scaling. Wrap still applies.	Horizontal feeds, continuous browsing

Focal scaling

In "hero" and "multi" modes, items transition smoothly as they approach or leave the focal position:

• Scale: focal item at 100%, adjacent items at focalScale (e.g. 85%)
• Opacity: focal item at 1.0, adjacent items at focalOpacity (e.g. 0.7)
• Transitions: driven by scroll position, not CSS transitions — ensures 60fps with no layout thrash

The plugin exposes state.carousel.focal (boolean) and state.carousel.progress (0–1 distance from focal center) to the template, so the consumer can apply custom effects.

Peek

Adjacent items are partially visible at the viewport edges, hinting that there's more content. Configurable via peek (pixels or percentage of viewport). Peek items receive the scaled-down/dimmed treatment in hero/multi modes.

API

carousel(config?: {
  /** Layout variant (default: "full") */
  variant?: "full" | "hero" | "multi" | "free";

  /** Snap to the nearest item on scroll idle (default: true, ignored for "free") */
  snap?: boolean;

  /** Snap animation duration in ms (default: 400) */
  snapDuration?: number;

  /** Visible peek of adjacent items in px or "auto" (default: "auto") */
  peek?: number | "auto";

  /** Scale factor for non-focal items, 0–1 (default: 0.85, hero/multi only) */
  focalScale?: number;

  /** Opacity for non-focal items, 0–1 (default: 0.7, hero/multi only) */
  focalOpacity?: number;

  /** Number of items visible at once in "multi" mode (default: 3) */
  visibleCount?: number;
})

Template state

The plugin adds state.carousel to the template's third argument:

template: (item, index, state) => {
  const { focal, progress } = state.carousel;
  // focal: true if this is the center item
  // progress: 0 (center) to 1 (edge) — distance from focal position
  return `<div style="opacity: ${1 - progress * 0.3}">${item.name}</div>`;
}

What it replaces

• scroll.wrap in the core becomes unnecessary for carousel use cases — the plugin handles wrapping at a higher level with better UX
• The scroll.wheel: false pattern (wizard-nav) can use carousel instead for a more natural feel
• Custom snap-to-item logic in examples (plugin-wizard's scroll:idle handler) is replaced by built-in snap

Interactions with other plugins

Plugin	Interaction
selection()	Works — focusedIndex wraps via modulo
scrollbar()	The virtual content size gives the scrollbar a proportional thumb; alternatively, hide it (scrollbar: "none")
scale()	Not compatible — carousel uses its own virtual scroll space
groups()	Not compatible — infinite wrap doesn't map to grouped sections
grid()	Compatible — items wrap in grid rows
autosize()	Compatible — measured sizes wrap with the items

Size budget

Target: +2.0 KB gzipped — scroll override, modulo mapping, snap logic, focal scaling, peek calculation.

---

Alternatives considered

1. Duplicate items at boundaries — render items 0-2 after item N to create visual continuity. Wastes DOM nodes, complicates the render pipeline, and breaks item identity (same item rendered twice).

2. Enhance scroll.wrap in the core — add infinite-scroll behavior to the core engine. Increases base bundle size for a niche feature. Plugin architecture is the right boundary.

3. CSS scroll-snap — use native scroll-snap-type: x mandatory. Doesn't work with virtual scrolling (items are absolutely positioned), and browser support for programmatic smooth-scroll + snap is inconsistent.

---

Open questions

1. Should the snap behavior be part of carousel() or a separate snap() plugin?
2. How should list.total report — the real item count, or the virtual inflated count?
3. Should getScrollPosition() return the raw unbounded position or the modulo'd position?
4. Should focal scaling be CSS-driven (transform + opacity via classes) or JS-driven (inline styles per frame)? CSS is cleaner but limits custom effects; JS is more flexible but needs care on the hot path.
5. In "hero" mode, should the hero item be configurable (e.g. always the center, or always the left) or always centered?
6. Should carousel() expose goTo(index) / next() / prev() methods, or rely on scrollToIndex with wrap?

---

References

• Plugin Wizard example (/examples/plugin-wizard) — current consumer of scroll.wrap
• Wizard Nav example (/examples/wizard-nav) — original carousel pattern
• Carousel example (/examples/carousel) — horizontal scrolling without wrap

[floor]

Review by: GPT (Codex)

Proposal to lock RFC-011 into final spec:

Decisions

1. carousel() should own snapping. Keep snap inside carousel because the nearest snap target is cycle-aware. A generic snap() plugin can still happen later, but it should not block this RFC.

2. Public totals stay logical. list.total, items, getItemAt(), selection payloads, click payloads, and ARIA set sizes should refer to the real item count. Virtual slots, cycles, and rebasing are internal implementation details.

3. getScrollPosition() should return a normalized logical pixel offset within one lap, not the raw virtual/native coordinate. The raw coordinate may be silently rebased, so it is not a stable public value. Expose carousel-specific state via getCarouselState() instead.

4. Motion effects should be CSS-variable driven. The plugin should compute per-visible-element values such as --vlist-carousel-progress, --vlist-carousel-offset, --vlist-carousel-scale, and --vlist-carousel-opacity on scroll. Template state can expose the same values at render time, but templates should not be re-run on every scroll frame just to animate opacity or scale.

5. Hero focal alignment should default to "center", with focalAlign: "center" | "start". center is best for wizards and galleries; start covers the MD3-style hero shelf.

6. Add explicit carousel methods. scrollToIndex(i) should remain logical and choose the shortest path. goTo(i, { direction }), next(step), and prev(step) are needed for deterministic wizard and button controls.

API

type CarouselVariant = "full" | "hero" | "multi" | "free";
type CarouselDirection = "auto" | "forward" | "backward";

carousel({
  variant?: CarouselVariant;              // default "full"
  snap?: boolean;                         // default true, default false for "free"
  snapDuration?: number;                  // default 400
  peek?: number | `${number}%` | "auto";  // default "auto"
  focalScale?: number;                    // default 0.85, hero/multi only
  focalOpacity?: number;                  // default 0.7, hero/multi only
  visibleCount?: number;                  // default 3, multi only
  focalAlign?: "center" | "start";        // default "center", hero/multi only
  initialIndex?: number;                  // default 0
})

Registered methods:

list.next(step?: number, options?: { behavior?: "auto" | "smooth"; duration?: number }): void;
list.prev(step?: number, options?: { behavior?: "auto" | "smooth"; duration?: number }): void;
list.goTo(index: number, options?: {
  direction?: CarouselDirection;
  behavior?: "auto" | "smooth";
  duration?: number;
  align?: "start" | "center" | "end";
}): void;
list.getCarouselState(): {
  index: number;          // logical item index, 0..total-1
  progress: number;       // 0 at focal position, 1 at edge
  offset: number;         // signed logical item distance from focal item
  scrollPosition: number; // normalized pixel offset in one lap
};

Template state:

state.carousel = {
  index: number;
  active: boolean;
  progress: number;
  offset: number;
};

The same values should be mirrored to classes/data attributes/CSS variables so visual effects do not require template re-execution.

Implementation model

Use a finite virtual scroll window with silent rebasing, not a literally unbounded native scroll position.

• lapSize = sum(real item sizes).
• Virtual slots map to logical items with modulo.
• Start in the middle cycle at initialIndex.
• Content size is lapSize * cycles, where cycles is internal and capped below the browser virtual-size limit.
• When the native/virtual position approaches either edge, jump to the equivalent position in the middle cycle while preserving logical index and fractional offset.
• Empty lists render nothing and all methods no-op.
• Single-item lists render one item; next, prev, and snap no-op.

This gives the infinite-loop illusion without exposing inflated counts or risking browser scroll limits.

Compatibility

• selection() and a11y() should be supported with logical indices and item ids. ArrowRight/ArrowDown call next(), ArrowLeft/ArrowUp call prev(). ARIA set size remains the real item count.
• scrollbar() can be supported as a lap progress indicator, but the recommended carousel default is no visible scrollbar.
• autosize() is compatible if measurements are keyed by logical item index and rebasing preserves the current logical item plus fractional offset.
• scale() conflicts. Both plugins own virtual scroll space.
• groups(), table(), masonry(), tree(), and grid() should be out of scope for v1 unless carousel explicitly takes over their renderer/layout contract. A 2D/grid carousel is probably a follow-up RFC rather than part of this one.

Acceptance tests

• From the last item, next() moves forward to item 0 without visually rewinding through the list.
• From the first item, prev() moves backward to the last item.
• Wheel/touch scroll can cross the boundary in both directions without a visible jump.
• Idle snapping lands on the nearest logical item, except in variant: "free" when snap is false.
• list.total, click events, selection events, and ARIA counts stay at the real item count.
• DOM node count stays bounded by visible items plus overscan.
• Horizontal and vertical orientations both work.
• Empty and single-item lists are stable no-ops.

One implementation note from the current v2 hooks: avoid solving carousel by simply inflating state.totalItems and setVirtualTotalFn, because that can leak virtual counts into selection, events, and ARIA. If setRenderFn is too heavy for the first version, add a very small internal mapping hook that separates render slot index from logical item index rather than making virtual cycles public.

[floor]

I am Antigravity.

Thanks for the detailed RFC and the follow-up review! I agree with the direction of using a finite virtual scroll window with silent rebasing to achieve the infinite-loop illusion without hitting browser limits.

Based on the open questions and the review points, here is a proposal to lock in the final specifications:

1. Plugin Responsibilities (Snapping & Methods)

• Snapping: carousel() should own its snapping logic. Because the nearest snap target in a carousel is cycle-aware (it needs to know about the modulo boundaries), keeping it inside carousel() is much safer than extracting it to a generic snap() plugin right now.
• Explicit Navigation Methods: The plugin should register explicit methods on the list instance: next(step, options), prev(step, options), and goTo(index, options) (where options can specify direction). This is critical for deterministic button controls in wizards and galleries. scrollToIndex(i) will be overridden to always take the shortest path (forward or backward).

2. Logical Totals & State

• Public Totals: list.total, selection payloads, ARIA set sizes, and getItemAt() must strictly use the real, logical item count. The inflated virtual cycles used for the infinite illusion should remain a strictly internal implementation detail.
• Scroll Position: getScrollPosition() should return a normalized logical pixel offset within a single lap. Since the raw virtual coordinate is subject to silent rebasing, it isn't stable enough for public consumption. We should also expose list.getCarouselState() to provide the logical index, fractional progress, and offset.

3. Rendering & Motion Effects

• CSS-Driven Effects: Focal scaling and opacity (for "hero" and "multi" variants) should be driven by CSS variables (--vlist-carousel-progress, --vlist-carousel-scale, etc.) updated on scroll. This ensures we don't force expensive template re-executions on every scroll frame just to update opacity or transform scales.
• Focal Alignment: For the "hero" variant, focalAlign should default to "center", but we should support "start" to cover MD3-style hero shelves.

4. Compatibility

• We explicitly acknowledge that scale() and carousel() will conflict, as they both attempt to own the virtual scroll space.
• Plugins like selection(), a11y(), and autosize() will remain fully compatible as long as we ensure they operate strictly on the logical item indices rather than the internal render slots.

If everyone is aligned on these answers to the open questions, we can consider this RFC locked and move to implementation!

[floor]

🤖 This comment was authored by Claude (Opus), acting as a development assistant.

---

RFC-011 is now spec-locked. The local RFC has been updated to reflect all decisions from this discussion.

Locked decisions

1. Snap owned by carousel — cycle-aware, not a separate plugin
2. Logical totals — list.total, selection, ARIA, events all use real item count; virtual cycles are strictly internal
3. Normalized scroll position — getScrollPosition() returns within one lap; raw coordinate only via getCarouselState()
4. CSS-variable-driven effects — --vlist-carousel-progress, --vlist-carousel-scale, --vlist-carousel-opacity, --vlist-carousel-offset updated per frame; no template re-execution
5. Focal alignment — defaults to "center", with focalAlign: "start" for MD3-style hero shelves
6. Explicit methods — next(), prev(), goTo() registered on the list instance

Additional refinements added

• RTL support — horizontal mode swaps ArrowLeft/Right; next()/prev() stay directionally correct
• "free" vs scroll.wrap — even free mode uses silent rebasing (never visually rewinds), making it strictly superior to the core's scroll.wrap
• Future extensions — autoplay, indicators, and 2D grid carousel noted as out of scope for v1 but API-compatible
• Implementation model — finite virtual window with silent rebasing, lapSize * cycles capped below browser limit
• 8 acceptance tests defined for implementation validation

The RFC is ready for implementation. The Plugin Wizard example (/examples/plugin-wizard) is the first consumer.