README

A Filament form field powered by Flatpickr — date, time, range, week, month, year, and multi-date picking with a fluent API.

Supported versions

Installation

Install the package with Composer:

composer require coolsam/flatpickr

Publish assets and configuration:

php artisan flatpickr:install

This publishes config/flatpickr.php and assets to public/vendor/flatpickr. You will be prompted to overwrite existing files when upgrading.

After upgrading, refresh Filament assets:

php artisan filament:upgrade

Quick start

use Coolsam\Flatpickr\Forms\Components\Flatpickr;

Flatpickr::make('published_at')
    ->format('Y-m-d')
    ->minDate(today()->startOfYear())
    ->maxDate(today());

Picker modes

One component covers every Flatpickr mode you need:

Short examples

use Coolsam\Flatpickr\Forms\Components\Flatpickr;

Flatpickr::make('start_time')->timePicker();
Flatpickr::make('week_number')->weekPicker()->format('W Y');
Flatpickr::make('month')->monthPicker()->format('Y-m')->displayFormat('F Y');
Flatpickr::make('year')->yearPicker();
Flatpickr::make('range')->rangePicker();
Flatpickr::make('starts_at')->rangePicker()->rangeEnd('ends_at')->format('Y-m-d');
Flatpickr::make('occupied_slots')->multiplePicker()->format('Y-m-d')->displayFormat('F j, Y');

Configuration

Most fluent methods mirror Flatpickr's options. The API is inspired by Filament's date/time fields and works as a drop-in alternative with Flatpickr-specific behaviour.

use Coolsam\Flatpickr\Enums\FlatpickrMode;
use Coolsam\Flatpickr\Enums\FlatpickrMonthSelectorType;
use Coolsam\Flatpickr\Enums\FlatpickrPosition;
use Coolsam\Flatpickr\Forms\Components\Flatpickr;

Flatpickr::make('event_date')
    ->format('Y-m-d')
    ->displayFormat('F j, Y')
    ->allowInput()
    ->altInput()
    ->minDate(fn () => today()->startOfYear())
    ->maxDate(fn () => today())
    ->disableDates(['2024-07-25', '2024-07-26'])
    ->rangeSeparator(' to ')
    ->conjunction(',')
    ->hourIncrement(1)
    ->minuteIncrement(10)
    ->seconds(false)
    ->weekNumbers()
    ->time24hr()
    ->inline()
    ->disableMobile()
    ->mode(FlatpickrMode::RANGE) // or ->rangePicker(), ->multiplePicker()
    ->monthSelectorType(FlatpickrMonthSelectorType::DROPDOWN)
    ->position(FlatpickrPosition::AUTO_CENTER)
    ->showMonths(2)
    ->timePicker()
    ->weekPicker()
    ->monthPicker()
    ->yearPicker()
    ->rangePicker()
    ->multiplePicker();

See the Flatpickr documentation for details on each option.

State types

Split range across two fields

When your model uses separate starts_at and ends_at columns, bind the range picker to the start field and name the end field explicitly. One picker is shown; both attributes are hydrated, synced live, and dehydrated on save.

Flatpickr::make('starts_at')
    ->label('Event dates')
    ->rangePicker()
    ->rangeEnd('ends_at')
    ->format('Y-m-d');

Do not add a second Flatpickr on ends_at. Validation rules on ends_at (for example after:starts_at) still work because the end value is kept in sync while the user selects a range.

Date & time range

Use ->time(true) with a format that includes hours and minutes. displayFormat() controls what the user sees in the input (Flatpickr tokens, not PHP date() tokens). Storage and dehydration still use format().

Flatpickr::make('starts_at')
    ->label('Event schedule')
    ->rangePicker()
    ->rangeEnd('ends_at')
    ->time(true)
    ->format('Y-m-d H:i')              // saved to starts_at / ends_at
    ->displayFormat('M j, Y h:i K')    // e.g. Jun 14, 2024 7:00 AM to Jun 17, 2024 5:00 PM
    ->rangeSeparator(' to ');

Ensure your model casts both columns as datetime. The picker UI lets you choose a date and time for each end of the range in one calendar.

See RFC 0001 for the full design.

Themes

Set the global theme in config/flatpickr.php using a FlatpickrTheme enum value:

use Coolsam\Flatpickr\Enums\FlatpickrTheme;

return [
    'theme' => FlatpickrTheme::DEFAULT, // recommended
];

Recommendation: Use the DEFAULT theme. It is styled with Tailwind to match Filament, including dark mode. Bundled Flatpickr themes may not align with your panel styling.

Theme previews are included in the screenshots below.

Screenshots

Picker modes

Single date

Multiple dates

Date range

Date & time

Time only

Multiple months

Week

Month

Theme gallery

Default (recommended)

Airbnb

Light

Dark

Confetti

Material Blue

Material Green

Material Orange

Material Red

Testing

composer test

Changelog

See CHANGELOG for release notes.

Contributing

See CONTRIBUTING for guidelines.

Security

Report vulnerabilities according to our security policy.

Credits

• Savannabits
• All Contributors

License

The MIT License. See LICENSE.md.