<x-widget.date-range-picker>
Date range picker Blade component for Laravel and Livewire
Start/end date picker with a multi-month popover. Submits two Y-m-d fields; validate them with NotAfterToday. Works with Livewire: wire:model binds an array's start and end.
php artisan bladewell:add date-range-picker
- Also adds
- Button, Date picker, Icon
- Needs PHP extension
intl- Works with
- Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+
- Guide
- Add a date range picker to a Laravel form
Usage
Livewire
In a Livewire component, bind with wire:model to an array with start and end keys, the shape name="period" submits: public array $period = ['start' => null, 'end' => null]. Both ends update together (wire:model.live sends them in one request), the field shows the property after every render, and a range set or cleared in PHP shows too. Errors are read under period.start and period.end, as the rules below report them.
<div>
<x-widget.date-range-picker label="Report period" wire:model.live="period" :max="false" />
{{-- In the component, in the Y-m-d the field sends (a request can send any two dates), the end not before the start.
For a range in the past, add new \App\Rules\NotAfterToday to both:
$this->validate(['period.start' => ['required', 'date_format:Y-m-d'], 'period.end' => ['required', 'date_format:Y-m-d', 'after_or_equal:period.start']]); --}}
</div>
On the server
The date range picker can't stop a request that skips it. Here's what to check on your server, and what to keep cheap.
Security
-
The picker keeps end after start and both in range, but a request can send any two dates. Validate both with
date_format:Y-m-d, and the end withafter_or_equal:the start field, along withNotAfterTodaywhere the range is in the past.
Server cost
-
A range is often a report: a wide one can scan years of rows. Consider capping how many days a request may ask for, indexing the date column, and caching results for closed periods once the data behind them is stable. Past data can still change (refunds, corrections, late imports), so use a short TTL or clear the cache when those records change.
Laravel: Cache · OWASP API4: Unrestricted resource consumption
Examples
Report period
Submits report_period[start] and report_period[end] as Y-m-d. By default nothing after today can be picked.
Show code Hide code
<x-widget.date-range-picker name="report_period" label="Report period" class="max-w-sm" />
Booking
For bookings: start from today, no upper limit.
Check-in to check-out.
Show code Hide code
<x-widget.date-range-picker name="stay" label="Stay" min="today" :max="false" info="Check-in to check-out." class="max-w-sm" />
With error
Errors are read from the session automatically; pass error to set one yourself.
Leave can be at most 5 days.
Show code Hide code
<x-widget.date-range-picker name="leave" label="Leave" start="2026-09-01" end="2026-09-10" error="Leave can be at most 5 days." class="max-w-sm" />
Props
Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.
<x-widget.date-range-picker>
| Prop | Default | Description |
|---|---|---|
| name |
null
|
Submits the range as name[start] and name[end]. Optional with wire:model, which binds an array's start and end. |
| start-name |
null
|
Or name the start field yourself (e.g. from). |
| end-name |
null
|
And the end field (e.g. to). |
| id |
null
|
Defaults to one made from the name (or the wire:model property). |
| label |
null
|
Shown above the field, and its name for screen readers. |
| start |
null
|
The first date: YYYY-MM-DD or a date object. Old input wins; with wire:model and no start or end, the bound property. |
| end |
null
|
The last date, the same way. A range that ends before it starts is dropped. |
| placeholder |
null
|
Shown while no range is picked; "Choose dates" by default. |
| error |
null
|
An error message of your own; otherwise the validation error for the name, from the session or Livewire. |
| info |
null
|
A hint under the field. |
| bag |
'default'
|
Which error bag to read the error from. |
| disabled |
false
|
Greyed out: it can't be opened. |
| readonly |
false
|
Shown, and submitted, but it can't be changed: the button opens nothing. With disabled, disabled wins. |
| min |
null
|
The earliest date that can be picked: YYYY-MM-DD, a date object, or "today" (the visitor's today). |
| max |
'today'
|
The latest date: YYYY-MM-DD, a date object, "today" (the default), or false for no limit. |
| week-start |
null
|
The first day of the week, 0 (Sunday) to 6 (Saturday); defaults to the locale's. |
| months |
2
|
2 shows two months side by side where the screen is wide enough (one on phones); 1 always shows one. |
| locale |
null
|
The language for month and day names and the date shown (en, fr, ar…); defaults to the app's. |
| required-message |
'Choose a start and an end date.'
|
With required: the message when nothing is picked. |
Accessibility
All 3 examples above are checked with axe-core against the WCAG 2.2 A and AA rules, in the light theme and the dark one, both as the page draws and with each popover, dialog, toast and tooltip opened, on every change. A change that fails can't be merged. Where axe can't decide, such as contrast on SVG text, the test measures the colours itself instead of letting it pass.
Automated checks can't judge everything: how it sounds in a screen reader, and how it feels to use from the keyboard, still need a person. Check those on your own pages too.
Source
What bladewell:add date-range-picker writes to your app with the default namespaces. Prefer to copy by hand? Take these files, plus the ones from
the components it also adds and Field, and the theme and base CSS.
resources/views/components/widget/date-range-picker/index.blade.php Show
resources/js/widget/date-range-picker/index.js Show
app/View/Widget/ElementIds.php Show
app/View/Widget/FormField.php Show
app/View/Widget/LocalDate.php Show
app/Rules/LocalToday.php Show
app/Rules/NotAfterToday.php Show