> ## Documentation Index
> Fetch the complete documentation index at: https://filament-34a8cf01.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Date-time picker
> [!WARNING]
>
> You are currently viewing the documentation for Filament 4.x, which is a previous version of Filament.
>
> Looking for the current stable version? Visit the [5.x documentation](https://filament-34a8cf01.mintlify.site/5.x/forms/date-time-picker.md).
## Introduction
The date-time picker provides an interactive interface for selecting a date and/or a time.
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DatePicker;
use Filament\Forms\Components\DateTimePicker;
use Filament\Forms\Components\TimePicker;
DateTimePicker::make('published_at')
DatePicker::make('date_of_birth')
TimePicker::make('alarm_at')
```
Loading preview
## Customizing the storage format
You may customize the format of the field when it is saved in your database, using the `format()` method. This accepts a string date format, using [PHP date formatting tokens](https://www.php.net/manual/en/datetime.format.php):
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->format('d/m/Y')
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
## Disabling the seconds input
When using the time picker, you may disable the seconds input using the `seconds(false)` method:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->seconds(false)
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
Loading preview
## Timezones
If you'd like users to be able to manage dates in their own timezone, you can use the `timezone()` method:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->timezone('America/New_York')
```
While dates will still be stored using the app's configured timezone, the date will now load in the new timezone, and it will be converted back when the form is saved.
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
If you do not pass a `timezone()` to the component, it will use Filament's default timezone. You can set Filament's default timezone using the `FilamentTimezone::set()` method in the `boot()` method of a service provider such as `AppServiceProvider`:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Support\Facades\FilamentTimezone;
public function boot(): void
{
FilamentTimezone::set('America/New_York');
}
```
This is useful if you want to set a default timezone for all date-time pickers in your application. It is also used in other places where timezones are used in Filament.
### Timezones for date-only fields
`DatePicker` and `DateTimePicker::make()->time(false)` use the app's timezone, ignoring both `timezone()` and Filament's default timezone. Plain dates are interpreted in the app's timezone; values with an offset or timezone, including Eloquent's serialized dates, are converted to the app's timezone before determining the selected date. This applies to native and JavaScript pickers, including custom calendar storage formats.
Use a `DateTimePicker` with a time input if you need to preserve the time as well as the date.
#### Storing date-only values as Unix timestamps
A storage `format()` containing an unescaped `U` token is an exception: it uses `timezone()` or the app's timezone to determine the selected date. Filament's default timezone still does not apply to these date-only fields.
## Enabling the JavaScript date picker
By default, Filament uses the native HTML5 date picker. You may enable a more customizable JavaScript date picker using the `native(false)` method:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->native(false)
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
Loading preview
> [!NOTE]
>
> The JavaScript date picker does not allow direct date entry. Use the native date picker if users need to type dates.
### Customizing the display format
You may customize the display format of the field, separately from the format used when it is saved in your database. For this, use the `displayFormat()` method, which also accepts a string date format, using [PHP date formatting tokens](https://www.php.net/manual/en/datetime.format.php):
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->native(false)
->displayFormat('d/m/Y')
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
Loading preview
You may also configure the locale that is used when rendering the display, if you want to use different locale from your app config. For this, you can use the `locale()` method:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->native(false)
->displayFormat('d F Y')
->locale('fr')
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
### Configuring the time input intervals
You may customize the input interval for increasing/decreasing the hours/minutes /seconds using the `hoursStep()` , `minutesStep()` or `secondsStep()` methods:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->native(false)
->hoursStep(2)
->minutesStep(15)
->secondsStep(10)
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
### Configuring the first day of the week
In some countries, the first day of the week is not Monday. To customize the first day of the week in the date picker, use the `firstDayOfWeek()` method on the component. 0 to 7 are accepted values, with Monday as 1 and Sunday as 7 or 0:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->native(false)
->firstDayOfWeek(7)
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
Loading preview
There are additionally convenient helper methods to set the first day of the week more semantically:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->native(false)
->weekStartsOnMonday()
DateTimePicker::make('published_at')
->native(false)
->weekStartsOnSunday()
```
### Disabling specific dates
To prevent specific dates from being selected:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('date')
->native(false)
->disabledDates(['2000-01-03', '2000-01-15', '2000-01-20'])
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
Loading preview
### Closing the picker when a date is selected
To close the picker when a date is selected, you can use the `closeOnDateSelection()` method:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('date')
->native(false)
->closeOnDateSelection()
```
Optionally, you may pass a boolean value to control if the input should close when a date is selected or not:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('date')
->native(false)
->closeOnDateSelection(FeatureFlag::active())
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
## Autocompleting dates with a datalist
Unless you're using the [JavaScript date picker](#enabling-the-javascript-date-picker), you may specify [datalist](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist) options for a date picker using the `datalist()` method:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\TimePicker;
TimePicker::make('appointment_at')
->datalist([
'09:00',
'09:30',
'10:00',
'10:30',
'11:00',
'11:30',
'12:00',
])
```
Datalists provide autocomplete options to users when they use the picker. However, these are purely recommendations, and the user is still able to type any value into the input. If you're looking to strictly limit users to a set of predefined options, check out the [select field](https://filament-34a8cf01.mintlify.site/4.x/forms/select.md).
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
### Focusing a default calendar date
By default, if the field has no state, opening the calendar panel will open the calendar at the current date. This might not be convenient for situations where you want to open the calendar on a specific date instead. You can use the `defaultFocusedDate()` to set a default focused date on the calendar:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DatePicker;
DatePicker::make('custom_starts_at')
->native(false)
->placeholder(now()->startOfMonth())
->defaultFocusedDate(now()->startOfMonth())
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
Loading preview
## Adding affix text aside the field
You may place text before and after the input using the `prefix()` and `suffix()` methods:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DatePicker;
DatePicker::make('date')
->prefix('Starts')
->suffix('at midnight')
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
Loading preview
### Using icons as affixes
You may place an [icon](https://filament-34a8cf01.mintlify.site/4.x/styling/icons.md) before and after the input using the `prefixIcon()` and `suffixIcon()` methods:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\TimePicker;
use Filament\Support\Icons\Heroicon;
TimePicker::make('at')
->prefixIcon(Heroicon::Play)
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
Loading preview
#### Setting the affix icon's color
Affix icons are gray by default, but you may set a different color using the `prefixIconColor()` and `suffixIconColor()` methods:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\TimePicker;
use Filament\Support\Icons\Heroicon;
TimePicker::make('at')
->prefixIcon(Heroicon::CheckCircle)
->prefixIconColor('success')
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
Loading preview
## Making the field read-only
Not to be confused with [disabling the field](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#disabling-a-field), you may make the field "read-only" using the `readonly()` method:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->readonly()
```
This setting applies to both native and [JavaScript date pickers](#enabling-the-javascript-date-picker). Read-only JavaScript date pickers remain focusable, but cannot open the picker or clear the value.
There are a few differences, compared to [`disabled()`](./overview#disabling-a-field):
* When using `readOnly()`, the field will still be sent to the server when the form is submitted. It can be mutated with the browser console, or via JavaScript. You can use [`saved(false)`](./overview#preventing-a-field-from-being-saved) to prevent this.
* There are no styling changes, such as less opacity, when using `readOnly()`.
* The field is still focusable when using `readOnly()`.
Optionally, you may pass a boolean value to control if the field should be read-only or not:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->readOnly(FeatureFlag::active())
```
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
## Date-time picker validation
As well as all rules listed on the [validation](https://filament-34a8cf01.mintlify.site/4.x/forms/validation.md) page, there are additional rules that are specific to date-time pickers.
### Max date / min date validation
You may restrict the minimum and maximum date that can be selected with the picker. The `minDate()` and `maxDate()` methods accept a `DateTime` instance (e.g. `Carbon`), or a string:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->native(false)
->minDate(now()->subYears(150))
->maxDate(now())
```
For date-only fields (`DatePicker` or `DateTimePicker::make()->time(false)`), the time portion of each limit is ignored. The entire minimum and maximum calendar dates are allowed, without converting the limits to another timezone.
For time-only fields (`TimePicker` or `DateTimePicker::make()->date(false)`), the date portion of each limit is ignored. The minimum time must not be later than the maximum time; these limits do not support ranges that cross midnight.
When using `seconds(false)`, seconds are ignored when checking both the selected value and its limits. For example, a minimum of `09:30:23` allows any value in the `09:30` minute, and a maximum of `17:45:47` allows the entire `17:45` minute. This does not change your storage `format()` or remove seconds already preserved by it.
[Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
[Edit this page on GitHub](https://github.com/filamentphp/filament/edit/4.x/packages/forms/docs/08-date-time-picker.md)
## Sponsored by
[Your logo here](https://github.com/sponsors/danharrin)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.