Carousel

A scroll-snap carousel built on the native scroll container, so touch swipe, trackpad and momentum work out of the box. Mouse drag, keyboard, autoplay and looping are layered on top. Compose it from nana-carousel-item slides and pick behaviour through attributes.

Anatomy

carousel.html

html

1	<nana-carousel navigation="arrows dots" loop>
2	<nana-carousel-item><img src="/1.jpg" alt="…" /></nana-carousel-item>
3	<nana-carousel-item><img src="/2.jpg" alt="…" /></nana-carousel-item>
4	<nana-carousel-item><img src="/3.jpg" alt="…" /></nana-carousel-item>
5	</nana-carousel>

Navigation

Combine tokens with spaces — arrows, dots, numbers, progress.

navigation="arrows"

navigation="dots"

navigation="arrows dots"

navigation="numbers"

navigation="progress"

navigation.html

html

1	<nana-carousel navigation="arrows"></nana-carousel>
2	<nana-carousel navigation="dots"></nana-carousel>
3	<nana-carousel navigation="arrows dots"></nana-carousel>
4	<nana-carousel navigation="numbers"></nana-carousel>
5	<nana-carousel navigation="progress"></nana-carousel>

Multi-item & Peek

slides-per-view="3"

peek

multi.html

html

1	<!-- Multiple slides per view -->
2	<nana-carousel slides-per-view="3" navigation="arrows dots" loop>…</nana-carousel>
3
4	<!-- Peek the neighbours -->
5	<nana-carousel peek navigation="arrows dots" loop>…</nana-carousel>

Autoplay

Pauses on hover / focus and when the tab is hidden, and is skipped entirely under prefers-reduced-motion.

autoplay.html

html

1	<nana-carousel autoplay interval="3500" loop navigation="progress">…</nana-carousel>

Hero variant

Slide 1

Slide 2

Slide 3

Slide 4

Slide 5

Slide 6

States

error

Import

main.ts

1	import "@nana-tec/ui-components/carousel";
2	// the item registers with it, or import on its own:
3	import "@nana-tec/ui-components/carousel-item";

Events

Event	Detail
`nana-slide-change`	`{ index: number, total: number }`

  Customization
         
   carousel.css     css   
 
       1  nana-carousel.brand {  
  2    --nana-carousel-gap: 1.5rem;  
  3    --nana-carousel-radius: 1rem;  
  4    --nana-carousel-accent: #2563eb;  
  5    --nana-carousel-peek: 3rem;  
  6  }  
 
 
 
 
      CSS 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 the neighbour peeks (peek mode)  
 --nana-carousel-height  Viewport height (vertical orientation)  
 
 
 
  Styling internals with ::part()
 
Target the exposed parts —
base,
viewport,
nav-prev /
nav-next,
pagination.
    1234  
 
         
   parts.css     css   
 
       1  nana-carousel::part(nav-prev),  
  2  nana-carousel::part(nav-next) {  
  3    border-radius: 0.5rem;  
  4    background: #0f172a;  
  5    color: #fff;  
  6    border-color: #0f172a;  
  7  }  
 
 
 
 
    Usage recipes
   Image gallery
            
  Product cards — slides-per-view + peek
    
  Headphones
 $29.00
 
 
   
  Keyboard
 $58.00
 
 
   
  Mouse
 $87.00
 
 
   
  Monitor
 $116.00
 
 
   
  Webcam
 $145.00
 
 
   
  Testimonials — autoplay + centred
    “Nana UI shipped our design system in a week.”
 Ada — CTO, Northwind
 
   “The carousel just worked, on every framework.”
 Lee — Eng, Initech
 
   
 
  Props
     Attribute  Type  Default  Description  
 
   variant  default | cards | hero | gallery | testimonial  default  Visual style  
 orientation  horizontal | vertical  horizontal  Scroll axis  
 navigation  arrows dots numbers progress  arrows dots  Controls (space-combinable)  
 slides-per-view  number  1  Slides visible at once  
 autoplay  boolean  false  Advance automatically  
 interval  number  5000  Autoplay interval (ms)  
 pause-on-hover  boolean  true  Pause autoplay on hover / focus  
 loop  boolean  false  Wrap around at the ends  
 peek  boolean  false  Show a peek of adjacent slides  
 draggable  boolean  true  Allow mouse drag-to-scroll  
 disabled  boolean  false  Disable all interaction  
 loading  boolean  false  Show a skeleton placeholder  
 error  string  —  Replace the track with an alert  
 
 
 
  Accessibility
  The viewport is a focusable role="region" with aria-roledescription="carousel"; slides are role="group" labelled "n of total".
 Keyboard: ←/→ (or ↑/↓ when vertical) move between slides; Home / End jump to the ends.
 Arrow and dot controls have descriptive labels; the dot for the active slide carries aria-current.
 Autoplay pauses on hover / focus and is disabled under prefers-reduced-motion.

Attribute	Type	Default	Description
`variant`	`default \| cards \| hero \| gallery \| testimonial`	`default`	Visual style
`orientation`	`horizontal \| vertical`	`horizontal`	Scroll axis
`navigation`	`arrows dots numbers progress`	`arrows dots`	Controls (space-combinable)
`slides-per-view`	`number`	`1`	Slides visible at once
`autoplay`	`boolean`	`false`	Advance automatically
`interval`	`number`	`5000`	Autoplay interval (ms)
`pause-on-hover`	`boolean`	`true`	Pause autoplay on hover / focus
`loop`	`boolean`	`false`	Wrap around at the ends
`peek`	`boolean`	`false`	Show a peek of adjacent slides
`draggable`	`boolean`	`true`	Allow mouse drag-to-scroll
`disabled`	`boolean`	`false`	Disable all interaction
`loading`	`boolean`	`false`	Show a skeleton placeholder
`error`	`string`	`—`	Replace the track with an alert

1	nana-carousel.brand {
2	--nana-carousel-gap: 1.5rem;
3	--nana-carousel-radius: 1rem;
4	--nana-carousel-accent: #2563eb;
5	--nana-carousel-peek: 3rem;
6	}

CSS 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 the neighbour peeks (peek mode)
`--nana-carousel-height`	Viewport height (vertical orientation)

1	nana-carousel::part(nav-prev),
2	nana-carousel::part(nav-next) {
3	border-radius: 0.5rem;
4	background: #0f172a;
5	color: #fff;
6	border-color: #0f172a;
7	}