README

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

Supported versions

Package	Filament	Laravel	PHP
v5.x (current)	4.x, 5.x	11.x – 13.x	8.2 – 8.5 (PHP 8.5 from Laravel 12+; Laravel 13 from PHP 8.3+)
v4.x	3.x	10.x – 11.x	8.1 – 8.3
v2.x	2.x	9.x – 10.x	8.0 – 8.2

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:

Mode	Helper	Typical format
Date	`Flatpickr::make('date')`	`Y-m-d`
Date & time	`->time(true)` or `->timePicker()`	`Y-m-d H:i` / `H:i`
Range	`->rangePicker()`	array of date strings, or two fields with `->rangeEnd()`
Multiple dates	`->multiplePicker()`	array of date strings
Week	`->weekPicker()`	`W Y`
Month	`->monthPicker()`	`Y-m`
Year	`->yearPicker()`	`Y`

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

Picker	Dehydrated state
Date, time, week, month, year	`string` or `CarbonInterface`
Range, multiple	`array` of date strings or `CarbonInterface` instances
Range with `->rangeEnd('ends_at')`	Two separate fields: start and end strings or `CarbonInterface` instances

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.