README

A powerful Flatpickr date/time picker integration for Filament v4. Features timezone handling, date ranges, multiple date selection, time slots, business hours, and 9 built-in themes.

Note: This project was heavily inspired by https://github.com/coolsam726/flatpickr. It was developed as a ground-up alternative with a focus on current Laravel and Filament versions and tailored Filament integration. Many thanks to the original project for the ideas and motivation.

Requirements

PHP 8.3+
Laravel 11+
Filament v4
Livewire 3

Installation

Install the package via Composer:

composer require citricguy/filament-flatpickr

Publish the assets (required):

php artisan filament:assets

Quick Start

use Citricguy\FilamentFlatpickr\Forms\Components\Flatpickr;

Flatpickr::make('published_at')
    ->dateTime()

Available Components

The package provides one main component with three convenience wrappers:

Component	Description
`Flatpickr`	Full-featured base component
`FlatpickrDatePicker`	Pre-configured date-only picker
`FlatpickrTimePicker`	Pre-configured time-only picker
`FlatpickrDateTimePicker`	Pre-configured date+time picker

use Citricguy\FilamentFlatpickr\Forms\Components\FlatpickrDatePicker;
use Citricguy\FilamentFlatpickr\Forms\Components\FlatpickrTimePicker;
use Citricguy\FilamentFlatpickr\Forms\Components\FlatpickrDateTimePicker;

FlatpickrDatePicker::make('birth_date')

FlatpickrTimePicker::make('alarm_time')

FlatpickrDateTimePicker::make('appointment_at')

Selection Modes

Date Only

Flatpickr::make('date')
    ->dateOnly()

Time Only

Flatpickr::make('time')
    ->timeOnly()

Date and Time

Flatpickr::make('datetime')
    ->dateTime()

Date Range

Select a start and end date:

Flatpickr::make('vacation')
    ->range()

For storing start/end dates in separate database columns:

Flatpickr::make('vacation')
    ->range()
    ->dualStatePaths('vacation_start', 'vacation_end')

Multiple Dates

Select multiple individual dates:

Flatpickr::make('blocked_dates')
    ->multiple()

Time Configuration

24-Hour Format

Flatpickr::make('time')
    ->timeOnly()
    ->time24hr()

Include Seconds

Flatpickr::make('precise_time')
    ->timeOnly()
    ->seconds()

Time Increments

Flatpickr::make('appointment')
    ->dateTime()
    ->hourIncrement(1)
    ->minuteIncrement(15)

Business Hours

Restrict selection to business hours (validation enforced):

Flatpickr::make('meeting')
    ->dateTime()
    ->businessHours('09:00', '17:00')

Time Slots

Enforce fixed time slot intervals:

Flatpickr::make('appointment')
    ->dateTime()
    ->useTimeSlots()
    ->timeSlotDurationMinutes(30)

Default Time

Set default hour and minute when opening the picker:

Flatpickr::make('start_time')
    ->dateTime()
    ->defaultHour(9)
    ->defaultMinute(0)

Date Constraints

Minimum and Maximum Dates

Flatpickr::make('future_date')
    ->dateOnly()
    ->minDate(now())
    ->maxDate(now()->addYear())

Date Restrictions

use Citricguy\FilamentFlatpickr\Enums\DateRestriction;

// No past dates
Flatpickr::make('future_event')
    ->dateOnly()
    ->dateRestriction(DateRestriction::NoPast)

// No future dates
Flatpickr::make('birth_date')
    ->dateOnly()
    ->dateRestriction(DateRestriction::NoFuture)

Disable Specific Weekdays

// Disable weekends (0 = Sunday, 6 = Saturday)
Flatpickr::make('business_day')
    ->dateOnly()
    ->disabledWeekdays([0, 6])

Exclude Specific Dates

Flatpickr::make('available_date')
    ->dateOnly()
    ->excludedDates(['2025-12-25', '2025-01-01'])

Range Duration Constraints

For range mode, constrain the minimum and maximum duration:

Flatpickr::make('rental_period')
    ->range()
    ->minRangeMinutes(60 * 24)      // Minimum 1 day
    ->maxRangeMinutes(60 * 24 * 14) // Maximum 14 days

Timezone Handling

Display and Storage Timezones

Flatpickr::make('event_at')
    ->dateTime()
    ->displayTimezone('America/New_York')
    ->storageTimezone('UTC')

Timezone Modes

use Citricguy\FilamentFlatpickr\Enums\TimezoneMode;

// Use app's default timezone
Flatpickr::make('event_at')
    ->timezoneMode(TimezoneMode::LocationDefault)

// Use a fixed timezone
Flatpickr::make('event_at')
    ->timezoneMode(TimezoneMode::Fixed)
    ->displayTimezone('Europe/London')

// Detect user's browser timezone
Flatpickr::make('event_at')
    ->timezoneMode(TimezoneMode::Submitter)

Formats

Storage Format

The format used when saving to the database:

Flatpickr::make('date')
    ->format('Y-m-d H:i:s')

Default formats by mode:

Date only: Y-m-d
Time only: H:i:s
DateTime: Y-m-d H:i:s

Display Format

The format shown to the user (uses Flatpickr tokens):

Flatpickr::make('date')
    ->displayFormat('F j, Y')
    ->useAltInput()

Appearance

Themes

use Citricguy\FilamentFlatpickr\Enums\FlatpickrTheme;

Flatpickr::make('date')
    ->theme(FlatpickrTheme::Dark)

Available themes:

Default
Airbnb
Confetti
Dark
Light
MaterialBlue
MaterialGreen
MaterialOrange
MaterialRed

Position

use Citricguy\FilamentFlatpickr\Enums\FlatpickrPosition;

Flatpickr::make('date')
    ->position(FlatpickrPosition::AboveRight)

Available positions: Auto, Above, Below, AutoLeft, AutoCenter, AutoRight, AboveLeft, AboveCenter, AboveRight, BelowLeft, BelowCenter, BelowRight

Inline Calendar

Display the calendar inline (always visible):

Flatpickr::make('date')
    ->inline()

Show Multiple Months

Flatpickr::make('date_range')
    ->range()
    ->showMonths(2)

Week Numbers

Flatpickr::make('date')
    ->weekNumbers()

UI Options

Allow Manual Input

Flatpickr::make('date')
    ->allowInput()

Disable Mobile Native Picker

Flatpickr::make('date')
    ->disableMobile()

Disable Click to Open

Flatpickr::make('date')
    ->clickOpens(false)

Close on Select

Flatpickr::make('date')
    ->closeOnSelect(false) // Keep open after selection

Prefixes and Suffixes

Works with Filament's standard affix system:

Flatpickr::make('date')
    ->prefixIcon('heroicon-o-calendar')
    ->suffixIcon('heroicon-o-clock')

Localization

Flatpickr::make('date')
    ->locale('fr')

Flatpickr supports 40+ locales.

Livewire Event Hooks

Emit Livewire events when the picker state changes:

Flatpickr::make('date')
    ->emitOnChange('dateSelected', ['dateStr', 'selectedDates'])
    ->emitOnOpen('pickerOpened')
    ->emitOnClose('pickerClosed')

Listen in your Livewire component:

#[On('dateSelected')]
public function handleDateChange(string $dateStr, array $selectedDates): void
{
    // Handle the event
}

Enums Reference

FlatpickrMode

use Citricguy\FilamentFlatpickr\Enums\FlatpickrMode;

FlatpickrMode::Single   // Default single date/time
FlatpickrMode::Range    // Date range selection
FlatpickrMode::Multiple // Multiple date selection

FlatpickrTheme

use Citricguy\FilamentFlatpickr\Enums\FlatpickrTheme;

FlatpickrTheme::Default
FlatpickrTheme::Airbnb
FlatpickrTheme::Confetti
FlatpickrTheme::Dark
FlatpickrTheme::Light
FlatpickrTheme::MaterialBlue
FlatpickrTheme::MaterialGreen
FlatpickrTheme::MaterialOrange
FlatpickrTheme::MaterialRed

FlatpickrPosition

use Citricguy\FilamentFlatpickr\Enums\FlatpickrPosition;

FlatpickrPosition::Auto
FlatpickrPosition::Above
FlatpickrPosition::Below
FlatpickrPosition::AutoLeft
FlatpickrPosition::AutoCenter
FlatpickrPosition::AutoRight
FlatpickrPosition::AboveLeft
FlatpickrPosition::AboveCenter
FlatpickrPosition::AboveRight
FlatpickrPosition::BelowLeft
FlatpickrPosition::BelowCenter
FlatpickrPosition::BelowRight

DateRestriction

use Citricguy\FilamentFlatpickr\Enums\DateRestriction;

DateRestriction::None     // No restriction
DateRestriction::NoPast   // Disable past dates
DateRestriction::NoFuture // Disable future dates

TimezoneMode

use Citricguy\FilamentFlatpickr\Enums\TimezoneMode;

TimezoneMode::LocationDefault // Use app timezone
TimezoneMode::Fixed           // Use specified timezone
TimezoneMode::Submitter       // Detect browser timezone

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.

citricguy / filament-flatpickr

Maintainers

Details