Carousel Component

The Carousel component provides a fully-featured image carousel with navigation controls, slide indicators, and smooth transitions. It uses Alpine.js for client-side interactivity and is fully compatible with Livewire for dynamic content.

Usage

Pass custom slides as an array. Each slide should contain an image source, alt text, title, description, and optional CTA button:

<x-carousel :slides="$slides" />

In your controller or Livewire component:

$slides = [
    [
        'imgSrc' => '/images/slide-1.jpg',
        'imgAlt' => 'Beautiful landscape',
        'title' => 'Welcome to Our Platform',
        'description' => 'Discover amazing features and tools.',
        'ctaUrl' => '/signup',
        'ctaText' => 'Get Started',
    ],
    [
        'imgSrc' => '/images/slide-2.jpg',
        'imgAlt' => 'Team collaboration',
        'title' => 'Work Together',
        'description' => 'Collaborate seamlessly with your team.',
        'ctaUrl' => '/features',
        'ctaText' => 'Learn More',
    ],
];

Livewire Integration

The carousel works seamlessly with Livewire. Pass slides from your Livewire component:

<x-carousel :slides="$this->slides" />

In your Livewire component:

class HeroCarousel extends Component
{
    public array $slides = [];

    public function mount()
    {
        $this->slides = [
            [
                'imgSrc' => '/images/promotion-1.jpg',
                'imgAlt' => 'Special promotion',
                'title' => 'Limited Time Offer',
                'description' => 'Get 50% off on all plans this month.',
                'ctaUrl' => '/pricing',
                'ctaText' => 'View Plans',
            ],
            // ... more slides
        ];
    }

    public function render()
    {
        return view('livewire.hero-carousel');
    }
}

Slide Structure

Each slide in the slides array must follow this structure:

Key	Type	Required	Description
imgSrc	string	Yes	URL or path to the slide image
imgAlt	string	Yes	Alt text for the image (accessibility)
title	string	Yes	Title text displayed on the slide
description	string	Yes	Description text displayed below the title
ctaUrl	string|null	No	URL for the call-to-action button. If null, the button is hidden
ctaText	string	No	Text displayed on the call-to-action button

Autoplay

Enable automatic slide progression with the autoplay prop. You can also control the interval between slides:

<x-carousel :slides="$slides" :autoplay="true" :interval="3000" />

When autoplay is enabled, a pause/play button appears in the bottom-right corner, allowing users to control the autoplay.

Starting Index

Control which slide is displayed initially using the startIndex prop (1-based index):

<x-carousel :slides="$slides" :startIndex="2" />

Props Reference

Prop	Type	Default	Description
slides	array	Default 3 slides	Array of slide objects. Each slide must contain imgSrc, imgAlt, title, description, and optionally ctaUrl and ctaText
startIndex	int	1	The initial slide to display (1-based index). For example, 1 shows the first slide, 2 shows the second slide, etc.
autoplay	bool	false	Whether the carousel should automatically advance to the next slide. When enabled, a pause/play button appears in the bottom-right corner.
interval	int	5000	The time in milliseconds between automatic slide transitions when autoplay is enabled.

Features

• Navigation Controls: Previous and next buttons for manual navigation
• Slide Indicators: Clickable dots at the bottom to jump to any slide
• Smooth Transitions: Opacity-based transitions between slides (1000ms duration)
• Infinite Loop: Automatically loops from last slide to first and vice versa
• Autoplay: Optional automatic slide progression with pause/play controls
• Customizable Start Index: Control which slide is displayed initially
• Responsive Design: Adapts to different screen sizes with responsive padding and text sizes
• Accessibility: Proper ARIA labels and semantic HTML for screen readers
• Dark Mode Support: Full dark mode compatibility with theme-aware colors

Alpine.js Integration

The carousel uses Alpine.js for client-side interactivity. The component automatically initializes Alpine.js data with the slides array. Navigation (previous/next), indicator clicks, and autoplay controls are handled entirely on the client-side, making the carousel fast and responsive without server roundtrips.

References

Category	Path / Name	Description
Component	resources/views/components/carousel.blade.php	Carousel component file

For the detailed documentation, please visit the Penguin UI Carousels.