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

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

Method	Default	Description
`slidesPerView(int)`	`4`	Number of visible slides
`slidesPerGroup(int)`	`1`	Slides to advance per swipe
`spaceBetween(int)`	`20`	Gap between slides in pixels
`gridRows(int)`	`1`	Number of rows in grid layout
`direction(string)`	`'horizontal'`	`'horizontal'` or `'vertical'`
`height(string)`	`'auto'`	Container height (e.g. `'400px'`)
`width(string\|int)`	`'auto'`	Container width; integers auto-append `px`
`centeredSlides(bool)`	`false`	Center the active slide

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

Method	Default	Description
`responsiveGrid(bool)`	`false`	Enable responsive slide count
`minCardWidth(string\|int)`	`'200px'`	Min card width for calculation
`minCardHeight(string\|int)`	`'auto'`	Min 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'),

Method	Default	Description
`navigation(bool)`	`false`	Enable navigation arrows
`arrowPosition(string)`	`'header'`	`'header'`, `'items'`, or `'pagination'`
`navigationNextIcon(string\|Closure)`	`null`	Custom next arrow icon
`navigationPrevIcon(string\|Closure)`	`null`	Custom prev arrow icon

Pagination

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

Method	Default	Description
`pagination(bool)`	`false`	Enable pagination
`paginationType(string)`	`'bullets'`	`'bullets'`, `'fraction'`, or `'progressbar'`
`paginationClickable(bool)`	`false`	Allow clicking pagination bullets
`paginationDynamicBullets(bool)`	`false`	Dynamic bullet sizing
`paginationDynamicMainBullets(int)`	`1`	Number of main dynamic bullets
`paginationHideOnClick(bool)`	`false`	Hide pagination on click

Scrollbar

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

Method	Default	Description
`scrollbar(bool)`	`false`	Enable scrollbar
`scrollbarDragSize(int)`	`50`	Drag handle size
`scrollbarDraggable(bool)`	`false`	Allow dragging the scrollbar
`scrollbarSnapOnRelease(bool)`	`false`	Snap to slides on release
`scrollbarHide(bool)`	`true`	Auto-hide scrollbar

Autoplay

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

Method	Default	Description
`autoplay(bool)`	`false`	Enable autoplay
`autoplayDelay(int)`	`3000`	Delay between transitions (ms)

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

Method	Default	Description
`headerActions(array\|Closure)`	`[]`	Array of `Action` or `ActionGroup` instances
`showHeaderActionsOnHover(bool)`	`false`	Reveal actions only 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(),

Method	Default	Description
`cardActions(array\|Closure)`	`[]`	Array of `Action` or `ActionGroup` instances
`cardActionsPosition(string)`	`null` (auto)	`'top-right'`, `'top-left'`, `'bottom-right'`, `'right-edge'`
`showCardActionsOnHover(bool)`	`false`	Reveal actions only on hover

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

Getter	Default	Description
`getAllowTouchMove()`	`true`	Enable touch dragging
`getAllowSlideNext()`	`true`	Allow swiping forward
`getAllowSlidePrev()`	`true`	Allow swiping backward
`getGrabCursor()`	`false`	Show grab cursor
`getSimulateTouch()`	`true`	Simulate touch on desktop
`getThreshold()`	`5`	Min swipe distance (px)
`getTouchAngle()`	`45`	Allowed touch angle
`getSpeed()`	`300`	Transition speed (ms)

Keyboard & Mousewheel

Getter	Default
`getKeyboardEnabled()`	`false`
`getKeyboardOnlyInViewport()`	`true`
`getMousewheelEnabled()`	`false`
`getMousewheelForceToAxis()`	`false`
`getMousewheelSensitivity()`	`1`

Zoom

Getter	Default
`getZoomEnabled()`	`false`
`getZoomMaxRatio()`	`3`
`getZoomMinRatio()`	`1`
`getZoomToggle()`	`true`

Free Mode

Getter	Default
`getFreeModeEnabled()`	`false`
`getFreeModeMomentum()`	`true`
`getFreeModeMomentumBounce()`	`true`
`getFreeModeSticky()`	`false`

Virtual Slides

Getter	Default
`getVirtualEnabled()`	`false`
`getVirtualCache()`	`true`
`getVirtualAddSlidesBefore()`	`0`
`getVirtualAddSlidesAfter()`	`0`

Loop

Getter	Default
`getLoop()`	`false`
`getLoopAddBlankSlides()`	`true`
`getLoopAdditionalSlides()`	`0`
`getLoopPreventsSliding()`	`true`
`getRewind()`	`false`

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

License

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

codenzia / filament-carousel

Maintainers

Details