Skip to main content

​
Overview

The DateRangeFilter class provides a date range picker using Flatpickr, allowing users to select a start and end date. It supports custom date formats, min/max date constraints, and custom calendar styling.

​
Creating a DateRangeFilter

​
make
static method
required
Creates a new DateRangeFilter instance.
​
field
string
required
The database column name to filter on
DateRangeFilter::make('created_at')

​
Available Methods

​
label

​
label
method
Sets the display label for the filter.
​
label
string
required
The label text to display
DateRangeFilter::make('created_at')
    ->label('Created Between')

​
format

​
format
method
Sets the date format for display and parsing.
​
format
string
required
Date format string (PHP date format)
DateRangeFilter::make('event_date')
    ->format('Y-m-d')
Default: 'Y-m-d'

​
minDate

​
minDate
method
Sets the minimum selectable date.
​
date
string
required
Minimum date in ‘Y-m-d’ format
DateRangeFilter::make('created_at')
    ->minDate('2020-01-01')

​
maxDate

​
maxDate
method
Sets the maximum selectable date.
​
date
string
required
Maximum date in ‘Y-m-d’ format
DateRangeFilter::make('created_at')
    ->maxDate('2030-12-31')

​
calendarClass

​
calendarClass
method
Sets a custom CSS class for the Flatpickr calendar.
​
class
string
required
CSS class name(s)
DateRangeFilter::make('event_date')
    ->calendarClass('custom-calendar')

​
key

​
key
method
Overrides the internal key used for the filter.
​
key
string
required
Custom key identifier
DateRangeFilter::make('order.date')
    ->key('order_date_range')

​
default

​
default
method
Sets a default date range value for the filter.
​
value
mixed
required
The default value (array with ‘from’ and/or ‘to’ keys)
DateRangeFilter::make('created_at')
    ->default(['from' => '2024-01-01', 'to' => '2024-12-31'])

​
initialValue

​
initialValue
method
Sets an initial date range that is pre-applied when the table first loads.
​
value
mixed
required
The initial value (array with ‘from’ and/or ‘to’ keys)
DateRangeFilter::make('created_at')
    ->initialValue([
        'from' => now()->startOfMonth()->format('Y-m-d'),
        'to'   => now()->endOfMonth()->format('Y-m-d'),
    ])

​
filter

​
filter
method
Provides a custom query callback to override the default filter behavior.
​
callback
Closure
required
A closure that receives Builder $query and mixed $value (array with ‘from’ and ‘to’ keys) and returns the modified Builder
DateRangeFilter::make('created_at')
    ->label('Created Between')
    ->filter(function (Builder $query, mixed $value) {
        if (isset($value['from']) && $value['from'] !== '') {
            $query->whereDate('created_at', '>=', $value['from']);
        }
        if (isset($value['to']) && $value['to'] !== '') {
            $query->whereDate('created_at', '<=', $value['to']);
        }
        return $query;
    })

​
groupClass / labelClass / inputClass

​
groupClass
method
Sets CSS classes for the filter wrapper, label, or input element.
DateRangeFilter::make('created_at')
    ->groupClass('col-md-6')
    ->labelClass('font-semibold')
    ->inputClass('form-control-lg')

​
Value Structure

The filter value is an array with from and to keys: 
[
    'from' => '2024-01-01',
    'to'   => '2024-12-31',
]
Either key can be omitted or empty, allowing for open-ended ranges: 
['from' => '2024-01-01']  // Only start date
['to' => '2024-12-31']    // Only end date
['from' => '', 'to' => '']  // No filter applied

​
Value Clamping

Date values are automatically clamped to stay within minDate/maxDate bounds and normalized to ‘Y-m-d’ format internally: 
DateRangeFilter::make('created_at')
    ->format('m/d/Y')
    ->minDate('2024-01-01')
    ->maxDate('2024-12-31')
Dates are converted from the display format to ‘Y-m-d’ for database queries.

​
Default Behavior

By default, DateRangeFilter applies whereDate queries with >= and <=: 
if ($value['from'] !== null && $value['from'] !== '') {
    $query->whereDate($fieldName, '>=', $value['from']);
}

if ($value['to'] !== null && $value['to'] !== '') {
    $query->whereDate($fieldName, '<=', $value['to']);
}

​
Complete Examples

​
Basic Usage

use Livewire\Tables\Filters\DateRangeFilter;

public function filters(): array
{
    return [
        DateRangeFilter::make('created_at')
            ->label('Created Between')
            ->format('Y-m-d')
            ->minDate('2020-01-01')
            ->maxDate('2030-12-31'),

        DateRangeFilter::make('published_at')
            ->label('Published Between'),

        DateRangeFilter::make('event_date')
            ->label('Event Date Range')
            ->format('m/d/Y')
            ->calendarClass('event-calendar'),
    ];
}

​
Pre-applied Date Range

use Livewire\Tables\Filters\DateRangeFilter;

public function filters(): array
{
    return [
        // Default to current month
        DateRangeFilter::make('created_at')
            ->label('Created This Month')
            ->initialValue([
                'from' => now()->startOfMonth()->format('Y-m-d'),
                'to'   => now()->endOfMonth()->format('Y-m-d'),
            ]),

        // Default to last 30 days
        DateRangeFilter::make('updated_at')
            ->label('Updated (Last 30 Days)')
            ->initialValue([
                'from' => now()->subDays(30)->format('Y-m-d'),
                'to'   => now()->format('Y-m-d'),
            ]),
    ];
}

​
Custom Filter Logic

use Livewire\Tables\Filters\DateRangeFilter;
use Illuminate\Database\Eloquent\Builder;

public function filters(): array
{
    return [
        DateRangeFilter::make('order_date')
            ->label('Order Date Range')
            ->filter(function (Builder $query, mixed $value) {
                if (isset($value['from']) && $value['from'] !== '') {
                    $query->where('order_date', '>=', $value['from']);
                }
                if (isset($value['to']) && $value['to'] !== '') {
                    $query->where('order_date', '<=', $value['to']);
                }
                return $query;
            }),

        DateRangeFilter::make('created_at')
            ->label('Created Between (with time)')
            ->filter(function (Builder $query, mixed $value) {
                if (isset($value['from']) && $value['from'] !== '') {
                    $query->where('created_at', '>=', $value['from'] . ' 00:00:00');
                }
                if (isset($value['to']) && $value['to'] !== '') {
                    $query->where('created_at', '<=', $value['to'] . ' 23:59:59');
                }
                return $query;
            }),
    ];
}

​
Usage in Table Component

use App\Models\Order;
use Illuminate\Database\Eloquent\Builder;
use Livewire\Tables\Filters\DateRangeFilter;
use Livewire\Tables\Filters\SelectFilter;
use Livewire\Tables\Livewire\DataTableComponent;

class OrdersTable extends DataTableComponent
{
    public function query(): Builder
    {
        return Order::query();
    }

    public function filters(): array
    {
        return [
            DateRangeFilter::make('created_at')
                ->label('Order Date')
                ->format('Y-m-d')
                ->minDate('2020-01-01'),

            DateRangeFilter::make('shipped_at')
                ->label('Shipped Between'),

            SelectFilter::make('status')
                ->label('Status')
                ->setOptions([
                    'pending'   => 'Pending',
                    'shipped'   => 'Shipped',
                    'delivered' => 'Delivered',
                ]),
        ];
    }
}

​
Date Format Examples

// US format
DateRangeFilter::make('date')
    ->format('m/d/Y')

// European format
DateRangeFilter::make('date')
    ->format('d/m/Y')

// ISO format (default)
DateRangeFilter::make('date')
    ->format('Y-m-d')

// With time
DateRangeFilter::make('date')
    ->format('Y-m-d H:i')

​
UI Rendering

The filter renders a single input field that opens a Flatpickr calendar in range mode when clicked. Users can select a start and end date, which are displayed in the input field separated by ” to ”.

Build docs developers (and LLMs) love

Get started for freeTalk to us