README

A highly flexible, responsive carousel component for Filament PHP v4, powered by Swiper.js. Supports horizontal and vertical scrolling, responsive grids, card actions, header actions, and extensive UI customization.

Requirements

• PHP 8.1+
• Laravel 12+
• Filament v4

Installation

Install via Composer:

composer require codenzia/filament-carousel

Optionally, publish the views for customization:

php artisan vendor:publish --tag="filament-carousel-views"

Panel Plugin Registration

Register the plugin in your Filament panel provider:

use Codenzia\FilamentCarousel\FilamentCarouselPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentCarouselPlugin::make(),
        ]);
}

Quick Start

The Carousel component is a Filament Infolist Entry. Use it inside any Infolist schema:

use Codenzia\FilamentCarousel\Widgets\Carousel;
use Filament\Schemas\Schema;
use Filament\Schemas\Components\TextEntry;
use Filament\Support\Icons\Heroicon;

Carousel::make('projects')
    ->label('Active Projects')
    ->icon(Heroicon::Briefcase)
    ->navigation()
    ->slidesPerView(3)
    ->spaceBetween(20)
    ->cardSchema(fn (Schema $schema, $record) => $schema->components([
        TextEntry::make('name')->label('Project'),
        TextEntry::make('status')->badge(),
    ])),

Configuration Reference

Layout

Responsive Grid

Enable dynamic slide count calculation based on container width:

Carousel::make('items')
    ->responsiveGrid()
    ->minCardWidth(250)      // Minimum card width for calculation
    ->minCardHeight(180),    // Minimum card height

When enabled, slidesPerView is calculated as: floor(containerWidth / (minCardWidth + spaceBetween)).

Navigation Arrows

Carousel::make('items')
    ->navigation()
    ->arrowPosition('header')
    ->navigationNextIcon('heroicon-o-chevron-right')
    ->navigationPrevIcon('heroicon-o-chevron-left'),

Pagination

Carousel::make('items')
    ->pagination()
    ->paginationType('bullets')
    ->paginationClickable()
    ->paginationDynamicBullets(),

Scrollbar

Carousel::make('items')
    ->scrollbar()
    ->scrollbarDraggable()
    ->scrollbarHide(false),

Autoplay

Carousel::make('items')
    ->autoplay()
    ->autoplayDelay(5000),

Additional autoplay getters: getAutoplayDisableOnInteraction(), getAutoplayPauseOnMouseEnter(), getAutoplayReverseDirection(), getAutoplayStopOnLastSlide(), getAutoplayWaitForTransition().

Effects

Carousel::make('items')
    ->effect('coverflow'),

Supported effects: 'slide' (default), 'fade', 'cube', 'coverflow', 'flip', 'cards'.

Each effect has dedicated configuration getters (e.g. getCoverflowEffectDepth(), getCubeEffectShadow(), getCardsEffectPerSlideOffset()).

Card Schema

Define the content of each card using Filament's Schema builder. The closure receives a Schema instance and the current $record:

use Filament\Schemas\Schema;
use Filament\Schemas\Components\TextEntry;
use Filament\Schemas\Components\ImageEntry;

Carousel::make('team')
    ->label('Team Members')
    ->cardSchema(fn (Schema $schema, $record) => $schema->components([
        ImageEntry::make('avatar')->circular(),
        TextEntry::make('name')->weight('bold'),
        TextEntry::make('role')->color('gray'),
    ])),

Card View Props

Pass additional data to custom card views:

Carousel::make('items')
    ->cardViewProps(['showAvatar' => true, 'size' => 'lg']),

Actions

Header Actions

Display Filament Actions in the carousel header area:

use Filament\Actions\Action;

Carousel::make('projects')
    ->label('Projects')
    ->navigation()
    ->headerActions([
        Action::make('create')
            ->label('New Project')
            ->icon('heroicon-o-plus')
            ->action(fn () => redirect()->route('projects.create')),
    ])
    ->showHeaderActionsOnHover(),  // Only visible on hover

Card Actions

Display per-card actions (bound to each record automatically):

use Filament\Actions\Action;
use Filament\Actions\ActionGroup;

Carousel::make('milestones')
    ->cardActions([
        ActionGroup::make([
            Action::make('edit')
                ->label('Edit')
                ->icon('heroicon-o-pencil')
                ->action(fn ($record) => /* edit logic */),
            Action::make('delete')
                ->label('Delete')
                ->icon('heroicon-o-trash')
                ->color('danger')
                ->requiresConfirmation()
                ->action(fn ($record) => $record->delete()),
        ]),
    ])
    ->cardActionsPosition('top-right')
    ->showCardActionsOnHover(),

When position is null, it auto-detects: 'top-right' for horizontal carousels, 'right-edge' for vertical.

Item Click Action

Make the entire card clickable to trigger a Livewire action:

Carousel::make('tasks')
    ->itemClickAction('editTask'),

The clicked record is automatically passed as the action argument.

Title Click Action

Make the carousel heading clickable:

Carousel::make('tasks')
    ->label('My Tasks')
    ->titleAction('viewAllTasks'),

Extra Attributes

Add custom HTML attributes to the carousel container:

Carousel::make('items')
    ->extraAttributes(['class' => 'my-custom-class', 'data-section' => 'featured'])
    ->addClass('another-class')
    ->addClasses(['class-a', 'class-b']),

Advanced Swiper Options

The carousel exposes the full Swiper.js API through fluent getters. These are pre-configured with sensible defaults but can be accessed or overridden:

Touch & Interaction

Keyboard & Mousewheel

Zoom

Free Mode

Virtual Slides

Loop

Full Example

use Codenzia\FilamentCarousel\Widgets\Carousel;
use Filament\Actions\Action;
use Filament\Actions\ActionGroup;
use Filament\Schemas\Schema;
use Filament\Schemas\Components\TextEntry;
use Filament\Support\Icons\Heroicon;

Carousel::make('milestones')
    ->label('Milestones')
    ->icon(Heroicon::Flag)
    ->navigation()
    ->arrowPosition('header')
    ->slidesPerView(3)
    ->spaceBetween(16)
    ->responsiveGrid()
    ->minCardWidth(300)
    ->autoplay()
    ->autoplayDelay(5000)
    ->headerActions([
        Action::make('create')
            ->label('Add Milestone')
            ->icon('heroicon-o-plus'),
    ])
    ->showHeaderActionsOnHover()
    ->cardActions([
        ActionGroup::make([
            Action::make('edit')
                ->label('Edit')
                ->icon('heroicon-o-pencil'),
            Action::make('delete')
                ->label('Delete')
                ->icon('heroicon-o-trash')
                ->color('danger')
                ->requiresConfirmation(),
        ]),
    ])
    ->cardActionsPosition('top-right')
    ->showCardActionsOnHover()
    ->itemClickAction('viewMilestone')
    ->titleAction('viewAllMilestones')
    ->cardSchema(fn (Schema $schema, $record) => $schema->components([
        TextEntry::make('title')->weight('bold'),
        TextEntry::make('due_date')->date(),
        TextEntry::make('priority')->badge(),
    ])),

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Codenzia
• All Contributors

License

The MIT License (MIT). Please see License File for more information.