@carousel-kit/svelte

A lightweight, headless-friendly carousel for Svelte 5 (Runes), styled with Tailwind CSS + daisyUI. SSR-safe, fully typed, zero runtime dependencies beyond Svelte itself.

Install

npm install @carousel-kit/svelte

Requires svelte@^5.0.0 as a peer dependency, and (for the built-in styling) Tailwind CSS + daisyUI configured in your app.

Quick start

<script lang="ts">
	import { Carousel, CarouselSlide } from '@carousel-kit/svelte';
</script>

<Carousel loop navigation pagination>
	{#snippet children(ctrl)}
		<CarouselSlide>Slide 1</CarouselSlide>
		<CarouselSlide>Slide 2</CarouselSlide>
		<CarouselSlide>Slide 3</CarouselSlide>
	{/snippet}
</Carousel>

Components

| Export | Purpose | | --------------------- | ------------------------------------------------------------------ | | Carousel | Pre-wired shell — container, navigation, pagination, transitions | | CarouselSlide | A single slide; must be a direct child of Carousel's children | | CarouselNavigation | Prev/Next arrow buttons (used internally by Carousel) | | CarouselPagination | Dot bullets (used internally by Carousel) | | CarouselController | The reactive state/logic class powering everything above |

Sharing state with an external controller

Create a CarouselController outside your component tree to drive a slide counter, custom buttons, or a progress bar alongside the carousel:

<script lang="ts">
	import { Carousel, CarouselSlide, CarouselController } from '@carousel-kit/svelte';

	const ctrl = new CarouselController({ loop: true, autoplay: { delay: 4000 } });
</script>

<p>Slide {ctrl.activeIndex + 1} / {ctrl.slideCount}</p>

<Carousel controller={ctrl}>
	{#snippet children()}
		<CarouselSlide>Slide 1</CarouselSlide>
		<CarouselSlide>Slide 2</CarouselSlide>
	{/snippet}
</Carousel>

<button onclick={() => ctrl.prev()}>Prev</button>
<button onclick={() => ctrl.next()}>Next</button>

Key options

All of CarouselControllerOptions can be passed as props to <Carousel> or to new CarouselController(...) directly:

• slidesPerView, spaceBetween, slidesPerGroup, centeredSlides
• loop, direction ('horizontal' | 'vertical'), rtl, speed
• autoplay (boolean | AutoplayConfig)
• navigation, pagination (boolean or a config object)
• breakpoints — responsive overrides keyed by min-width in px
• keyboard, mousewheel, allowTouchMove, initialSlide
• onSlideChange, onInit, onReachEnd, onReachBeginning

See the exported CarouselControllerOptions / CarouselProps types for the full, documented list.

Current limitations: effect only supports 'slide' (other values are reserved for future use); slidesPerView: 'auto' is accepted by the types but not yet implemented (treated as 1).

Custom navigation/pagination

Override the built-in arrows or dots with a snippet, still backed by the same controller:

<Carousel navigation pagination>
	{#snippet navigationSnippet(ctrl)}
		<button onclick={() => ctrl.prev()}>←</button>
		<button onclick={() => ctrl.next()}>→</button>
	{/snippet}
	{#snippet children()}
		<CarouselSlide>Slide 1</CarouselSlide>
	{/snippet}
</Carousel>

Low-level building blocks

For a custom carousel-like UI, the package also exports the underlying utilities, constants, and types so you don't have to reimplement them: normaliseAutoplay, normalisePagination, normaliseBreakpoints, getCurrentBreakpoint, getResponsiveValue, getSlideAnimationClass, debounce, throttle, plus the CAROUSEL_* CSS class name constants and NAV_Z_INDEX/PAGINATION_Z_INDEX.

Accessibility

Navigation buttons and pagination dots ship with ARIA labels, roving tabindex, aria-selected/aria-current, and keyboard support. Enable keyboard on the controller for arrow-key/Home/End navigation of the carousel itself. Slide entrance animations respect prefers-reduced-motion.

License

MIT