3D carousel | Tuff Docs

Overview

TxCarousel3D renders real items and exposes their zero-based current index through v-model. Arc carousel, CoverFlow and Time Machine use independent source transforms. Every path has its own color and monochrome ID. Cards, previous/next controls, indicators and timeline all change the same current item.

Usage

Six source variants and custom content

Loading demo...

The demo shows all six IDs, supports filtering, and includes a real item slot. Its color thumbnails are original inline SVG landscapes. Time Machine has main ticks plus two intermediate ticks per interval; hovering, focusing, clicking or dragging the scrubber selects the nearest item.

Variant	Preserved source geometry
`card-carousel`	160px item spacing; hovered/focused offsets rotate 20° and move 24px vertically per step. Active scale 1.05; inactive scale 0.65 expanded, 0.8 collapsed.
`card-carousel-mono`	Same arc path, default slot displays caller-owned text instead of images.
`card-cover-flow`	1000px perspective; 32px spacing, ±38° side rotation, active depth +50px and 50px depth steps behind it. Cards beyond two steps fade out.
`card-cover-flow-mono`	Same CoverFlow path with text surfaces.
`card-time-machine`	800px perspective; depth −60px, vertical −12px and X rotation +2° per future step. Past cards move down 300px, forward 200px, rotate −20°, scale 1.3 and disappear.
`card-time-machine-mono`	Same depth stack and timeline with text surfaces.

The original ThreeDPage's three spatial specimens reuse these actual paths. No generic fan replaces the three geometries.

Best Practices

Give every item a stable id, title, and a date when using Time Machine. Supply src and alt only for images you are allowed to display.
Set loop only when wrapping is meaningful. The default stops and disables previous/next controls at the ends.
Leave expanded undefined for arc hover/focus behavior; set it to a boolean to control the arc pose. CoverFlow and Time Machine do not use this prop.
Use timelineHover=false when selection should wait for an explicit click. Keyboard focus still previews the tick geometry without selecting.
#item is inside a selection button and should contain non-interactive content. It can override the monochrome default without changing geometry.

API Reference

Props

Prop	Type	Default	Description
`items`	`MotionCardItem[]`	required	Caller-owned cards; empty arrays render `#empty`.
`modelValue`	`number`	internal `2`, Time Machine `0`	Current zero-based item; clipped to the available items.
`variant`	`Carousel3DVariant`	`card-carousel`	One of six IDs; `CAROUSEL_3D_VARIANTS` exports the list.
`expanded`	`boolean`	undefined	Controlled arc pose; otherwise hover/focus controls it.
`loop`	`boolean`	`false`	Wrap previous/next selection.
`animated`	`boolean`	`true`	Enable spatial motion without changing operations.
`disabled`	`boolean`	`false`	Disable card, control, tick and scrubber changes.
`controls`	`boolean`	`true`	Show previous/next controls.
`dots`	`boolean`	`true`	Show accessible item indicators.
`timeline`	`boolean`	`true`	Show Time Machine tick controls and range scrubber.
`timelineHover`	`boolean`	`true`	Tick hover/focus selects the nearest item.
`duration`	`number`	`800`	Shared-spring transition duration in milliseconds.
`size`	`xs / sm / md / lg`	`md`	Scale card dimensions and spatial paths together.
`ariaLabel`	`string`	`Card carousel`	Region accessible name.
`previousLabel`	`string`	`Previous`	Localizable control label.
`nextLabel`	`string`	`Next`	Localizable control label.
`itemLabel`	`string`	`Item`	Localizable indicator/item fallback name.
`timelineLabel`	`string`	`Timeline`	Localizable scrubber and tick accessible name.

MotionCardItem is shared with CardSpread: id?, title?, description?, src?, alt?, date?, href?, color?. Carousel defaults use title/description and, for color IDs, an optional image. No default assets or business records are embedded in the component.

Events

Event	Arguments	Meaning
`update:modelValue`	`index: number`	Current item requested by actual input.
`change`	`item: MotionCardItem, index: number`	Changed caller-owned item; unchanged indices do not emit.

Slots and instance methods

API	Contract
`#item`	`{ item, index, active }`; replaces a card's content.
`#caption`	`{ item, index, active: true }`; replaces the current caption.
`#empty`	Content for an empty items array.
`previous()` / `next()`	Use the same clamping/wrapping and disabled rules as controls.
`select(index)`	Select an item, rounding and clamping/wrapping the requested index.

Arrow keys select adjacent items; Home and End select boundary items. Native buttons support Enter/Space. The range scrubber retains its native keyboard behavior. Current captions are announced politely, and selection does not move focus unexpectedly.

Technologies

Ported from Amicro CardCarousel, CardCoverFlow, CardTimeMachine, cards.ts, card registry entries and the reused ThreeDPage specimens at commit 43c29ce9cdd16459e3eab4992381b8d35b38776a, under MIT, Copyright (c) 2026 SYED SUBHAN UDDIN.

CSS transforms use the shared spring compiler and useMotionActivity. Inactive/reduced motion renders the destination immediately without disabling selection. Time Machine's squircle filter uses a Vue useId identifier, so multiple instances and SSR hydration do not collide. No upstream image assets or React/Motion runtime are included.