@qwanyx/carousel

Universal slide/presentation engine for the Qwanyx ecosystem.

Features

• Polymorphic slides: Images, videos, documents, HTML, or custom React components
• Multiple transitions: Fade, slide, zoom, flip, cube
• Rich navigation: Arrows, dots, thumbnails, keyboard, touch/swipe
• Presentation mode: Fullscreen support with keyboard shortcuts
• Autoplay: With configurable intervals and pause-on-interaction
• Responsive: Adapts to any container size
• TypeScript: Full type safety

Installation

npm install @qwanyx/carousel

Quick Start

import { Carousel, createSlide } from '@qwanyx/carousel';

const slides = [
  createSlide.image('1', '/photo1.jpg', { title: 'Beautiful sunset' }),
  createSlide.image('2', '/photo2.jpg', { title: 'Mountain view' }),
  createSlide.video('3', '/video.mp4', { poster: '/poster.jpg' }),
];

function MyGallery() {
  return (
    <Carousel
      slides={slides}
      transition="fade"
      navigation={{ arrows: true, dots: true }}
      allowFullscreen
    />
  );
}

Slide Types

Image Slide

createSlide.image('id', '/image.jpg', {
  title: 'Image title',
  description: 'Description',
  alt: 'Alt text',
  objectFit: 'cover', // 'contain' | 'cover' | 'fill' | 'none'
});

Video Slide

createSlide.video('id', '/video.mp4', {
  poster: '/poster.jpg',
  autoplay: true,
  muted: true,
  loop: true,
  controls: true,
});

Document Slide (PDF)

createSlide.document('id', '/document.pdf', {
  title: 'My Document',
});

HTML Slide

createSlide.html('id', '<div>Custom HTML content</div>', {
  title: 'HTML Slide',
});

Component Slide

createSlide.component('id', () => <MyCustomComponent />, {
  title: 'Custom Component',
});

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | slides | Slide[] | required | Array of slides | | initialIndex | number | 0 | Starting slide index | | transition | TransitionType | 'fade' | Transition animation | | transitionDuration | number | 300 | Duration in ms | | navigation | NavigationOptions \| boolean | true | Navigation controls | | autoplay | AutoplayOptions \| boolean | false | Autoplay settings | | loop | boolean | false | Enable infinite loop | | aspectRatio | string | '16/9' | Container aspect ratio | | allowFullscreen | boolean | true | Enable fullscreen mode | | theme | 'light' \| 'dark' | 'dark' | Color theme | | onSlideChange | function | - | Callback on slide change |

Keyboard Shortcuts

| Key | Action | |-----|--------| | ← ↑ | Previous slide | | → ↓ | Next slide | | Space | Play/pause autoplay | | F | Toggle fullscreen | | Esc | Exit fullscreen |

Ref Methods

const carouselRef = useRef<CarouselRef>(null);

// Available methods:
carouselRef.current?.next();
carouselRef.current?.prev();
carouselRef.current?.goTo(2);
carouselRef.current?.getCurrentIndex();
carouselRef.current?.enterFullscreen();
carouselRef.current?.exitFullscreen();
carouselRef.current?.toggleFullscreen();
carouselRef.current?.play();
carouselRef.current?.pause();

License

MIT