Carousel Component - Amphibious 2.0 Documentation

Overview

The Amphibious Carousel component provides a flexible, accessible, and responsive carousel solution powered by Splide.js. It's perfect for image galleries, product showcases, testimonials, content slides, and more.

🚀 High Performance

Lightweight and optimized for smooth animations and fast load times.

♿ Accessibility First

Full keyboard navigation, screen reader support, and WCAG 2.1 AA compliance.

📱 Responsive Design

Adapts seamlessly to all screen sizes with configurable breakpoints.

🎨 Multiple Variants

Pre-built styles for cards, images, testimonials, and thumbnails.

⚙️ Flexible Configuration

Extensive options for customization via JavaScript or data attributes.

🔄 Auto-initialization

Automatically initializes from data attributes or manual JavaScript setup.

Quick Start

Basic HTML Structure

<!-- Auto-initialized carousel -->
<div class="amp-carousel amp-carousel--cards"
     data-carousel
     data-carousel-per-page="3"
     data-carousel-autoplay="true"
     aria-label="Featured products">
  <article>
    <h3>Product 1</h3>
    <p>Product description</p>
  </article>
  <article>
    <h3>Product 2</h3>
    <p>Product description</p>
  </article>
  <article>
    <h3>Product 3</h3>
    <p>Product description</p>
  </article>
</div>

JavaScript Initialization

// Create carousel with custom options
const carousel = amp.createCarousel('#my-carousel', {
  type: 'slide',
  perPage: 2,
  gap: '2rem',
  autoplay: true,
  interval: 3000,
  variant: 'cards'
});

Configuration Options

Option	Type	Default	Description
`variant`	string	'default'	Visual variant: 'default', 'cards', 'images', 'testimonials', 'thumbnails'
`size`	string	undefined	Size modifier: 'sm', 'md', 'lg', 'xl'
`type`	string	'slide'	Transition type: 'slide', 'loop', 'fade'
`perPage`	number	3	Number of slides visible per page
`gap`	string	'1rem'	Gap between slides
`autoplay`	boolean	false	Enable automatic slide progression
`interval`	number	5000	Autoplay interval in milliseconds
`arrows`	boolean	true	Show navigation arrows
`pagination`	string \| boolean	true	Pagination type: true, false, 'dots', 'progress', 'none'
`keyboard`	string	'global'	Keyboard navigation: 'global', 'focused', false

Data Attributes

Configure carousels using HTML data attributes for auto-initialization:

Attribute	Values	Description
`data-carousel`	-	Mark element for auto-initialization
`data-carousel-type`	slide, loop, fade	Set carousel transition type
`data-carousel-per-page`	number	Number of slides per page
`data-carousel-gap`	CSS value	Gap between slides (e.g., '2rem', '20px')
`data-carousel-variant`	cards, images, testimonials, thumbnails	Visual variant
`data-carousel-size`	sm, md, lg, xl	Size modifier
`data-carousel-autoplay`	true, false	Enable autoplay
`data-carousel-interval`	number	Autoplay interval in milliseconds
`data-carousel-arrows`	true, false	Show navigation arrows
`data-carousel-pagination`	dots, progress, none	Pagination type

CSS Classes

Base Classes

Class	Description
`.amp-carousel`	Base carousel container class

Variant Classes

Class	Description
`.amp-carousel--cards`	Card-style carousel with hover effects
`.amp-carousel--images`	Image gallery carousel
`.amp-carousel--testimonials`	Testimonial carousel with centered text
`.amp-carousel--thumbnails`	Thumbnail navigation carousel
`.amp-carousel--progress`	Progress bar pagination style

Size Modifier Classes

Class	Max Height	Description
`.amp-carousel--sm`	200px	Small carousel size
`.amp-carousel--md`	300px	Medium carousel size
`.amp-carousel--lg`	400px	Large carousel size
`.amp-carousel--xl`	500px	Extra large carousel size

JavaScript API

Creating a Carousel

// Basic creation
const carousel = amp.createCarousel('#my-carousel');

// With options
const carousel = amp.createCarousel('#my-carousel', {
  type: 'slide',
  perPage: 2,
  autoplay: true,
  variant: 'cards'
});

Instance Methods

Method	Parameters	Returns	Description
`mount()`	-	Splide	Initialize and mount the carousel
`destroy()`	-	void	Destroy the carousel and remove event listeners
`go(control)`	number \| string	void	Navigate to a specific slide (index, '>', '<')
`play()`	-	void	Start autoplay
`pause()`	-	void	Pause autoplay
`refresh()`	-	void	Refresh the carousel layout
`getSplide()`	-	Splide	Get the underlying Splide instance

Control Examples

// Navigation
carousel.go(2);     // Go to slide 2
carousel.go('>');   // Next slide
carousel.go('<');   // Previous slide
carousel.go('>>');  // Last slide
carousel.go('<<');  // First slide

// Playback control
carousel.play();
carousel.pause();

// Layout updates
carousel.refresh(); // Useful after dynamic content changes

Usage Examples

Image Gallery Carousel

<div class="amp-carousel amp-carousel--images amp-carousel--lg"
     data-carousel
     data-carousel-type="slide"
     data-carousel-per-page="1"
     aria-label="Photo gallery">
  <img src="https://picsum.photos/800/600?random=1" alt="Gallery image 1">
  <img src="https://picsum.photos/800/600?random=2" alt="Gallery image 2">
  <img src="https://picsum.photos/800/600?random=3" alt="Gallery image 3">
</div>

Product Cards Carousel

<div class="amp-carousel amp-carousel--cards"
     data-carousel
     data-carousel-per-page="3"
     data-carousel-gap="2rem"
     aria-label="Featured products">
  <article class="product-card">
    <img src="https://placehold.co/600x600/667eea/FFF?text=Product+1" alt="Product 1">
    <h3>Product Name</h3>
    <p class="price">$99.99</p>
    <button class="btn">Add to Cart</button>
  </article>
  <!-- More products... -->
</div>

Testimonials Carousel

<div class="amp-carousel amp-carousel--testimonials"
     data-carousel
     data-carousel-per-page="1"
     data-carousel-autoplay="true"
     data-carousel-interval="5000"
     aria-label="Customer testimonials">
  <blockquote>
    <p>"This product changed my life!"</p>
    <footer><cite>— Happy Customer</cite></footer>
  </blockquote>
  <!-- More testimonials... -->
</div>

Synced Carousels (Main + Thumbnails)

<!-- Main carousel -->
<div id="main-carousel" class="amp-carousel amp-carousel--images">
  <img src="main1.jpg" alt="Main view 1">
  <img src="main2.jpg" alt="Main view 2">
  <img src="main3.jpg" alt="Main view 3">
</div>

<!-- Thumbnail carousel -->
<div id="thumb-carousel" class="amp-carousel amp-carousel--thumbnails"
     data-carousel-arrows="false"
     data-carousel-pagination="none">
  <img src="https://picsum.photos/300/200?random=1" alt="Thumbnail 1">
  <img src="https://picsum.photos/300/200?random=2" alt="Thumbnail 2">
  <img src="https://picsum.photos/300/200?random=3" alt="Thumbnail 3">
</div>

<script>
// Sync the carousels
const main = amp.createCarousel('#main-carousel');
const thumbs = amp.createCarousel('#thumb-carousel');
main.getSplide().sync(thumbs.getSplide());
</script>

Accessibility Features

Keyboard Navigation

Full keyboard support with arrow keys, Enter, Space, Home, and End keys for navigation.

Screen Reader Support

Proper ARIA labels, roles, and announcements for slide changes and navigation.

Focus Management

Visible focus indicators and proper focus handling for all interactive elements.

Reduced Motion

Respects user's motion preferences and disables animations when requested.

High Contrast

Compatible with high contrast mode and provides alternative styling.

Semantic HTML

Uses proper semantic elements and maintains logical document structure.

Accessibility Best Practices

Always provide meaningful aria-label or aria-labelledby attributes
Use descriptive alt text for images
Include proper headings and semantic structure
Test with keyboard navigation and screen readers
Avoid auto-playing carousels unless absolutely necessary
Provide pause/play controls for auto-playing content

Performance Tips

Lazy Loading: Use loading="lazy" for images in slides
Image Optimization: Provide appropriately sized images for different viewports
Minimal DOM: Keep slide content minimal and avoid complex nested structures
Destroy Unused: Call carousel.destroy() when removing carousels from DOM
Responsive Images: Use srcset and sizes attributes for optimal image delivery

Browser Support

The Carousel component supports all modern browsers:

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+
iOS Safari 12+
Android Chrome 60+

For older browser support, polyfills for ES6 features may be required.