chrome

<tc-carousel>

Slide / fade carousel with autoplay, indicators, controls, keyboard nav, and pointer swipe. Slides go in the default slot.

import "@ra9/tan-compose-kit/carousel"

Props

Name	Type	Default	Description
`value`	`number`	`0`	Current slide index. Reflects to the `value` attribute.
`autoplay`	`number`	`0`	Autoplay interval in milliseconds. `0` disables autoplay.
`loop`	`boolean`	`true`	Wrap around at the ends. Disable to stop at first / last slide.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Slide axis. Vertical carousels require a `height`.
`transition`	`"slide" \| "fade"`	`"slide"`	How slides change. `slide` translates the track; `fade` cross-fades stacked slides.
`indicators`	`boolean`	`true`	Render dot indicators along the bottom (or right, vertical).
`controls`	`boolean`	`true`	Render the prev / next buttons.
`swipe`	`boolean`	`true`	Enable pointer / touch drag to change slides.
`pauseOnHover`	`boolean`	`true`	Pause autoplay while the carousel is hovered or focused.
`ariaLabel`	`string`	`"Carousel"`	Accessible region label.
`height`	`string`	`""`	Optional explicit viewport height (any CSS length). Required for vertical and fade carousels with images.

Events

Event	Detail	When
`tc-change`	`{ index: number, previous: number }`	Fires when the active slide changes (user click, swipe, keyboard, autoplay, or programmatic value change).

Slots

Slot	Description
`(default)`	One direct child per slide. The carousel observes children and updates as you add or remove slides.

CSS variables

Variable	Default	Description
`--tc-carousel-radius`	`var(--tc-radius-lg, 12px)`	Outer corner radius.
`--tc-carousel-bg`	`var(--tc-color-bg, #faf8f3)`	Background behind slides.
`--tc-carousel-control-bg`	`rgba(255, 255, 255, 0.85)`	Prev / next button background.
`--tc-carousel-control-bg-hover`	`rgba(255, 255, 255, 1)`	Prev / next button hover background.
`--tc-carousel-control-fg`	`var(--tc-color-ink, #14171f)`	Prev / next button icon color.
`--tc-carousel-control-size`	`36px`	Prev / next button diameter.
`--tc-carousel-indicator`	`rgba(20, 23, 31, 0.25)`	Indicator pill background.
`--tc-carousel-indicator-active`	`var(--tc-color-accent, #a16939)`	Active dot fill.
`--tc-carousel-duration`	`320ms`	Transition duration. Respected by both slide and fade modes.

Examples

Basic

The default carousel is a horizontal slide track with controls, indicators, looping, and pointer swipe. Each child of <tc-carousel> becomes a slide.

Slide 1

Slide 2

Slide 3

<tc-carousel ariaLabel="Featured"> <div>Slide 1</div> <div>Slide 2</div> <div>Slide 3</div> </tc-carousel>

Autoplay

Set autoplay to a millisecond interval. The carousel pauses on hover and on keyboard focus by default — turn that off with pauseOnHover="false" if you want it to keep cycling.

<tc-carousel autoplay="2500"> <div>A</div><div>B</div><div>C</div><div>D</div> </tc-carousel>

Fade transition

transition="fade" cross-fades slides stacked on top of each other. Set height so the viewport keeps a fixed size while content swaps.

"Tiny declarative library for building Web Components. No JSX, no compiler."
— release notes

"Refs, reactive props, and a focus-preserving render loop in 60 lines."
— v1.1.0

"Drop-in primitives. No global cascade, no framework runtime."
— kit v1.5.0

<tc-carousel transition="fade" autoplay="3000" height="180px"> <blockquote>"Quote one."</blockquote> <blockquote>"Quote two."</blockquote> <blockquote>"Quote three."</blockquote> </tc-carousel>

Vertical

orientation="vertical" rotates the track and indicators. A height is required so the viewport has a defined extent to scroll within.

One

Two

Three

<tc-carousel orientation="vertical" height="220px"> <div>One</div> <div>Two</div> <div>Three</div> </tc-carousel>

Indicators only, no controls

Hide the prev / next buttons for a more editorial feel. Indicators stay clickable.

Ship work, not config.

Drop into any page.

Native standards.

<tc-carousel controls="false" autoplay="2800"> <h2>Ship work, not config.</h2> <h2>Drop into any page.</h2> <h2>Native standards.</h2> </tc-carousel>

Image gallery

Carousels are most often used for image galleries. Set height so all slides share the same viewport regardless of intrinsic image size.

tan-01.jpg

tan-02.jpg

tan-03.jpg

tan-04.jpg

<tc-carousel autoplay="4000" height="260px"> <img src="/img/1.jpg" alt="…"> <img src="/img/2.jpg" alt="…"> <img src="/img/3.jpg" alt="…"> <img src="/img/4.jpg" alt="…"> </tc-carousel>

Listening for slide changes

<tc-carousel id="hero" autoplay="3000"> <div>One</div><div>Two</div><div>Three</div> </tc-carousel> <script> document.getElementById("hero").addEventListener("tc-change", (e) => { console.log("now on slide", e.detail.index, "from", e.detail.previous); }); </script>

Programmatic control

Set value to jump to a specific slide. The carousel reflects the prop to the value attribute, so two-way binding works with framework integrations.

const car = document.querySelector("tc-carousel"); car.value = 2; // jump to the third slide car.value = car.value + 1; // next

Accessibility

The root has role="region" and aria-roledescription="carousel". Set ariaLabel to something meaningful for screen readers.
Each slide gets role="group", aria-roledescription="slide", and aria-label="N of M" applied automatically.
A polite live region announces the new position on each change.
Keyboard support: ← / → (or ↑ / ↓ vertical) navigate, Home and End jump to the ends. Indicators are real <button> elements, focusable in source order.
prefers-reduced-motion: reduce collapses transitions to instant.

Theming

<tc-carousel style=" --tc-carousel-radius: 20px; --tc-carousel-bg: #0b0c10; --tc-carousel-control-bg: rgba(255,255,255,0.12); --tc-carousel-control-bg-hover: rgba(255,255,255,0.2); --tc-carousel-control-fg: #fff; --tc-carousel-duration: 500ms; " autoplay="3000" height="240px" >  </tc-carousel>

← All components