Carousel

Preview

Show code Copy

Installation

npm install @nana-tec/ui-components

Import

import "@nana-tec/ui-components/carousel";

Basic usage

<nana-carousel style="width:100%">
  <nana-carousel-item><img src="https://picsum.photos/seed/a/800/400" alt="Slide A" style="width:100%;display:block"></nana-carousel-item>
  <nana-carousel-item><img src="https://picsum.photos/seed/b/800/400" alt="Slide B" style="width:100%;display:block"></nana-carousel-item>
</nana-carousel>

Navigation

The navigation attribute controls the controls — arrows, dots, progress, numbers, or a space-separated combo. Add loop to wrap around.

Show code Copy

Multi-item & peek

Show several slides at once with slides-per-view, and hint the next slide with peek.

Show code Copy

API

Properties

Property	Attribute	Type	Default	Description
ariaLabel	aria-label	string | null	'Carousel'	Accessible label for the carousel region
autoplay	autoplay	boolean	false	Advance automatically
disabled	disabled	boolean	false	Disable all interaction
draggable	draggable	boolean	true	Allow mouse drag-to-scroll
error	error	string | undefined	—	Error message — replaces the track with an alert
interval	interval	number	5000	Autoplay interval (ms)
loading	loading	boolean	false	Show a loading skeleton instead of slides
loadingCount	loading-count	number	3	Number of skeleton slides while loading
loop	loop	boolean	false	Wrap around at the ends
navigation	navigation	string	'arrows dots'	Navigation controls — combine with spaces, e.g. "arrows dots"
orientation	orientation	CarouselOrientation	'horizontal'	Scroll axis
pauseOnHover	pause-on-hover	boolean	true	Pause autoplay on hover / focus
peek	peek	boolean	false	Show a peek of the adjacent slides (single-view only)
slidesPerView	slides-per-view	number	1	Slides visible at once (multi-item / cards)
variant	variant	CarouselVariant	'default'	Visual style

Events

Event	Description
nana-slide-change	Fired when the active slide changes (detail.index, detail.total)

Slots

Slot	Description
(default)	One or more nana-carousel-item slides
error	Custom error content (shown when error is set)

CSS parts

Part	Description
::part(base)	The outer container
::part(viewport)	The scrolling track
::part(nav-prev)	The previous-slide button
::part(nav-next)	The next-slide button
::part(pagination)	The dots / numbers / progress row

CSS custom properties

Property	Description
--nana-carousel-gap	Gap between slides
--nana-carousel-radius	Viewport corner radius
--nana-carousel-accent	Active dot / progress colour
--nana-carousel-peek	How much of the neighbour peeks (peek mode)
--nana-carousel-height	Viewport height (vertical orientation)
--nana-carousel-nav-bg	Background of the previous / next buttons
--nana-carousel-nav-color	Icon colour of the previous / next buttons
--nana-carousel-skeleton-height	Placeholder height before slides are measured
--nana-carousel-slide-basis	Width each slide flexes from; set this to show partial slides

Events

Event	Type	Description
nana-slide-change	CustomEvent	Fired when the active slide changes (detail.index, detail.total)

Slots

Slot	Description
(default)	One or more nana-carousel-item slides
error	Custom error content (shown when error is set)

CSS Variables

Variable	Description
--nana-carousel-gap	Gap between slides
--nana-carousel-radius	Viewport corner radius
--nana-carousel-accent	Active dot / progress colour
--nana-carousel-peek	How much of the neighbour peeks (peek mode)
--nana-carousel-height	Viewport height (vertical orientation)

CSS Parts

Part	Description
base	The outer container
viewport	The scrolling track
nav-prev	The previous-slide button
nav-next	The next-slide button
pagination	The dots / numbers / progress row

Accessibility

• Keyboard accessible
• Screen-reader labels
• Focus-visible states
• ARIA roles and states
• WCAG 2.2 AA contrast

Related components

• Table
• Carousel Item
• Image Comparer
• QR Code
• Icon

Storybook

Explore Carousel interactively Every state, prop, and edge case — with live controls — in Storybook.

View in Storybook