New: NativePHP Starter-Kit

Laravel Livewire Tables Documentation
Sponsors Demo Support

Edit

🎉 Enjoying this package? Consider sponsoring me on GitHub or buying me a beer.

This is the documentation for v3. You can switch versions in the menu at the top. Check your current version with the following command:

composer show rappasoft/laravel-livewire-tables

DateRange Filters

DateRange filters are Flatpickr based components, and simply filtering by a date range. If you would like to more smoothly filter your query by a start and end date, you can use the DateRangeFilter:

1use Rappasoft\LaravelLivewireTables\Views\Filters\DateRangeFilter;
2 
3public function filters(): array
4{
5    return [
6        DateRangeFilter::make('Verified Period'),
7    ];
8}

DateRange filters have configs to set earliestDate and latestDate, to allow/disallow input, to set the input format, to set a placeholder value, display format, plus Filter Pills labels

 1public function filters(): array
 2{
 3    return [
 4        DateRangeFilter::make('EMail Verified Range')
 5        ->config([
 6            'allowInput' => true,   // Allow manual input of dates
 7            'altFormat' => 'F j, Y', // Date format that will be displayed once selected
 8            'ariaDateFormat' => 'F j, Y', // An aria-friendly date format
 9            'dateFormat' => 'Y-m-d', // Date format that will be received by the filter
10            'earliestDate' => '2020-01-01', // The earliest acceptable date
11            'latestDate' => '2023-08-01', // The latest acceptable date
12            'placeholder' => 'Enter Date Range', // A placeholder value
13            'locale' => 'en',
14        ])
15        ->setFilterPillValues([0 => 'minDate', 1 => 'maxDate']) // The values that will be displayed for the Min/Max Date Values
16        ->filter(function (Builder $builder, array $dateRange) { // Expects an array.
17            $builder
18                ->whereDate('users.email_verified_at', '>=', $dateRange['minDate']) // minDate is the start date selected
19                ->whereDate('users.email_verified_at', '<=', $dateRange['maxDate']); // maxDate is the end date selected
20        }),
21    ];
22}

A full list of options is below, please see the Flatpickr documentation for reference as to purpose:

Config Option Type Default Description
allowInvalidPreload Boolean true Allows the preloading of an invalid date. When disabled, the field will be cleared if the provided date is invalid
allowInput Boolean false Allows the user to enter a date directly into the input field. By default, direct entry is disabled.
altFormat String "F j, Y" Exactly the same as date format, but for the altInput field
altInput Boolean false Show the user a readable date (as per altFormat), but return something totally different to the server.
ariaDateFormat String "F j, Y" Defines how the date will be formatted in the aria-label for calendar days, using the same tokens as dateFormat. If you change this, you should choose a value that will make sense if a screen reader reads it out loud.
dateFormat String 'Y-m-d' A string of characters which are used to define how the date will be displayed in the input box
defaultDate String null Sets the initial selected date
defaultHour Number 12 Initial value of the hour element.
defaultMinute Number 0 Initial value of the minute element.
earliestDate String/Date null The minimum date that a user can start picking from (inclusive)
enableTime Boolean false Enables time picker
enableSeconds Boolean false Enables seconds in the time picker.
hourIncrement Integer 1 Adjusts the step for the hour input (incl. scrolling)
latestDate String/Date null The maximum date that a user can pick to (inclusive)
locale String en The locale used (see below)
minuteIncrement Integer 5 Adjusts the step for the minute input (incl. scrolling)
placeholder String null Set a placeholder value for the input field
shorthandCurrentMonth Boolean false Show the month using the shorthand version (ie, Sep instead of September).
time_24hr Boolean false Displays time picker in 24 hour mode without AM/PM selection when enabled.
weekNumbers Boolean false Enables display of week numbers in calendar.

setFilterDefaultValue

You may use this to set a default value for the filter that will be applied on first load (but may be cleared by the user). This should be an array:

1DateRangeFilter::make('EMail Verified Range')
2    ->setFilterDefaultValue(['minDate' => '2024-05-05', 'maxDate' => '2024-06-06'])

or

1DateRangeFilter::make('EMail Verified Range')
2    ->setFilterDefaultValue(['min' => '2024-05-05', 'max' => '2024-06-06'])

or

1DateRangeFilter::make('EMail Verified Range')
2    ->setFilterDefaultValue(['2024-05-05', '2024-06-06'])

setPillsLocale

DateRange Filters also support the setPillsLocale method, which allows you to set a locale for use in generating the Filter Pills values

 1public function filters(): array
 2{
 3    return [
 4        DateRangeFilter::make('EMail Verified Range')
 5        ->setPillsLocale('fr ') // Use French localisation for the Filter Pills values
 6        ->config([
 7            'allowInput' => true,   // Allow manual input of dates
 8            'altFormat' => 'F j, Y', // Date format that will be displayed once selected
 9            'ariaDateFormat' => 'F j, Y', // An aria-friendly date format
10            'dateFormat' => 'Y-m-d', // Date format that will be received by the filter
11            'earliestDate' => '2020-01-01', // The earliest acceptable date
12            'latestDate' => '2023-08-01', // The latest acceptable date
13            'placeholder' => 'Enter Date Range', // A placeholder value
14            'locale' => 'en',
15        ])
16        ->setFilterPillValues([0 => 'minDate', 1 => 'maxDate']) // The values that will be displayed for the Min/Max Date Values
17        ->filter(function (Builder $builder, array $dateRange) { // Expects an array.
18            $builder
19                ->whereDate('users.email_verified_at', '>=', $dateRange['minDate']) // minDate is the start date selected
20                ->whereDate('users.email_verified_at', '<=', $dateRange['maxDate']); // maxDate is the end date selected
21        }),
22    ];
23}

Configuration

By default, this filter will inject the Flatpickr JS Library and CSS. However, you can customise this behaviour using the configuration file.

Option 1 - The default behaviour:

1'inject_third_party_assets_enabled' => true,

Option 2 - Bundled

If you choose to bundle the Tables JS/CSS (recommended) by adding the following to your build process:

1'vendor/rappasoft/laravel-livewire-tables/resources/js/laravel-livewire-tables-thirdparty.min.js';

or in your app.js

1import '../../vendor/rappasoft/livewire-tables/resources/js/laravel-livewire-tables-thirdparty.min.js';

Then you should disable injection to avoid conflicts:

1'inject_third_party_assets_enabled' => false,

Option 3 - CDN

You must ensure that Flatpickr is present PRIOR to the tables loading. For example, to add Flatpickr with the Spanish locale, ensure that the following is present in your Layout head section. Noting the "async" presence to ensure that the script is present before a page renders.

It is typically recommended not to utilise the CDN approach, as changes to core code may impact behaviour, and you may need to implement changes to your CSP if present.

If using the CDN approach, ensure the following config matches:

1'inject_third_party_assets_enabled' => false,

Then include the following in your layout:

1// Flatpickr Core Script
2<script src="https://npmcdn.com/flatpickr" defer></script>
3 
4// Flatpickr Core CSS
5<link rel="stylesheet" href="https://npmcdn.com/flatpickr/dist/flatpickr.min.css">

Option 4 - Locally Installed

If you have a locally installed version of Flatpickr already, you can set injection to false, and your local version will be used instead.

1'inject_third_party_assets_enabled' => false,

Localisation (BETA)

The default installation includes only the English (en) locale.

Bundling

Should you wish to localise, you must include the Flatpickr locale files in your build pipeline. This applies to only the specific locales that you require in your app.js (requires adding the flatpickr library to your package.json by executing "npm i flatpickr --save")

 1import { Arabic } from "../imports/flatpickr/l10n/ar.js";
 2import { Catalan } from "../imports/flatpickr/l10n/cat.js";
 3import { Danish } from "../imports/flatpickr/l10n/da.js";
 4import { German } from "../imports/flatpickr/l10n/de.js";
 5import { Spanish } from "../imports/flatpickr/l10n/es.js";
 6import { French } from "../imports/flatpickr/l10n/fr.js";
 7import { Indonesian } from "../imports/flatpickr/l10n/id.js";
 8import { Italian } from "../imports/flatpickr/l10n/it.js";
 9import { Malaysian } from "../imports/flatpickr/l10n/ms.js";
10import { Dutch } from "../imports/flatpickr/l10n/nl.js";
11import { Portuguese } from "../imports/flatpickr/l10n/pt.js";
12import { Russian } from "../imports/flatpickr/l10n/ru.js"
13import { Thai } from "../imports/flatpickr/l10n/th.js"
14import { Turkish } from "../imports/flatpickr/l10n/tr.js"
15import { Ukrainian } from "../imports/flatpickr/l10n/uk.js"

CDN

You can also add locales using the Flatpickr CDN, ensuring that these are loaded before the page renders.

For example to add German (de), ensure that the following is in the "head" section of your layout, ideally before your app.js

1<script src="https://npmcdn.com/flatpickr/dist/l10n/de.js" defer></script>