Download the PHP package harvirsidhu/filament-timepicker without Composer

Filament Smart Time Picker

A type-ahead time field for Filament. Your users just type — 3p, 330, 3:30 PM, 1530 — and a filterable, keyboard-navigable dropdown suggests times at whatever interval you pick. It looks and behaves like a native Filament field, but it's far more forgiving for the people filling in your forms all day.

Requirements: PHP 8.2+ · Filament v4 or v5

Contents

• What you get
• Quick start — install and use it in 3 steps
• How input parsing works
• Recipes — the common things you'll want to do
• API reference
• TimePicker
• Keyboard shortcuts
• Troubleshooting
• Translations
• How it works under the hood
• Contributing & development

What you get

• ⌨️ Forgiving free-text input — 3p, 9, 330, 1530, 9.30, 9h30 all parse to a clean 24-hour value.
• 📋 A suggestion dropdown at any interval you choose, filtered live as the user types.
• 🧭 Full keyboard control — arrow keys to move, Enter/Tab to pick, Esc to close.
• 🕒 Min / max bounds — only offer times inside a window (e.g. opening hours).
• ⏱️ Relative duration hints — show (30 mins), (1 hour), (1h 30m) next to each option, ideal for an "end time" that depends on a "start time".
• 🔒 Optional strict mode — confine values to the grid and reject anything off it.
• 🌍 Wall-clock safe — a 3 PM slot is always stored as 15:00. No surprise timezone shifts.
• 🎨 Native Filament look — same input chrome, light/dark aware, screen-reader friendly.
• 📱 Mobile-ready — a plain text input (no OS time-wheel hijack), touch-sized options, and a dropdown that stays in view when the on-screen keyboard opens.
• 🪶 Zero cost when unused — the JavaScript is lazy-loaded only on pages that have the field.

Quick start

1. Install the package

2. Publish the assets (copies the lazy-loaded JavaScript into /public)

3. Use it in a form

That's it. The field stores a plain H:i string like "15:30", so it drops straight into a time column with no casting or accessors.

Using a custom Filament theme? One extra step: add the package's views to your theme so Tailwind compiles the dropdown styles. In your theme's resources/css/filament/<panel>/theme.css:

Then rebuild: npm run build. (Skip this if you use Filament's default styling.)

How input parsing works

The whole point of this field is that people can type a time however they think of it, and it still ends up stored cleanly. Here's the mapping:

Separators are flexible. In the hh:mm part you can use a colon, a dot, or an h — so 9:30, 9.30 (common in the UK and Malaysia), and 9h30 (French) all parse to the same value.

Bad input never reaches your database. Parsing happens twice: instantly in JavaScript for a snappy feel, and authoritatively in PHP on the server. The server always has the final say, so a saved value is either a clean H:i (or H:i:s) string, or null.

Recipes

Set a default value

Use Filament's standard ->default(). It accepts the same forgiving formats and normalizes them for you:

->default('15:30'), ->default('330'), and ->default('3:30 PM') all work. For a dynamic default, pass a closure:

Filament only applies default() when creating a record, not when editing one.

Restrict to a window (e.g. opening hours)

minTime / maxTime accept a string, a Carbon instance, or a closure — so a bound can depend on another field:

Start & end times, with live duration labels

Point an "end time" at its "start time" with durationFrom(). The dropdown then only offers times after the start, and labels each option with how long the gap would be:

Each option is labelled with the gap from the start time: up to an hour in friendly words ((30 mins), (1 hour)), and past an hour in a compact form ((1h 30m), (2h)) so longer gaps stay short. Pass the sibling field's name ('start_time'), not its full path — durationFrom() resolves it for you, even inside repeaters and nested groups.

Auto-fill the end time from a default duration

Pair durationFrom() with defaultDuration() so picking (or changing) the start time fills the end time automatically. The user can still override it afterwards:

Choose any default — ->defaultDuration(10) lands on 12:10 pm. It fires only when the start time changes, so an existing end time on an edit form is left untouched, and the value is capped at maxTime() (or the end of the day) if the sum would overflow.

It keeps the gap. Whenever the end time differs from the default — set by the user, or by your own logic (an afterStateUpdated, a $set) — that gap is preserved on later start changes instead of snapping back to the default. Pick 12:00 pm → end fills to 12:30 pm; change the end to 1:00 pm (a 1-hour gap); move the start to 1:30 pm and the end follows to 2:30 pm, keeping the hour. The gap is read live (and runs client-side — no server roundtrip), and is seeded from an existing start/end pair on an edit form.

This is what lets a per-category duration coexist with the picker: set end_time from your own field (e.g. an appointment type's minutes) via afterStateUpdated, and the picker preserves that gap when the user nudges the start — without a Livewire roundtrip each time.

Show seconds

Change how the time is displayed

The visible text uses PHP date() tokens. The default is g:i a (e.g. 3:30 pm):

This only changes what's shown — the stored value is always canonical H:i/H:i:s.

Lock input to the grid (strict mode)

By default the field is forgiving: a user can type any valid time (e.g. 12:01) even if it isn't one of the suggested slots. Call strict() to confine values to the interval grid:

With strict on, typing an off-grid time snaps the box back to the last valid value as you go, and any off-grid value that bypasses the browser (a paste, a programmatic default, a CSV import) fails server-side validation with a clear message rather than being silently dropped.

API reference

All the usual Filament Field methods (->label(), ->required(), ->disabled(), ->prefixIcon(), ->placeholder(), ->live(), …) work as you'd expect.

Parsing time strings anywhere

The parser is a plain, dependency-free class you can reuse outside the field — in validation, imports, API endpoints, anywhere:

Migrating from Filament's TimePicker

It's a drop-in replacement. Swap the import and the class name — your existing call chain keeps working, because native() and timezone() are accepted as harmless no-ops:

Keyboard shortcuts

The field follows the ARIA combobox/listbox pattern, so it's fully operable from the keyboard and announced by screen readers.

Troubleshooting

The dropdown shows up unstyled (no colours, wrong layout). You're using a custom Filament theme and haven't told Tailwind about the package's views. Add the @source line from Quick start, then rebuild your theme with npm run build.

Nothing happens when I focus the field / the JS doesn't load. Run php artisan filament:assets and reload. This publishes (and re-publishes) the lazy-loaded component into /public. Re-run it any time the package updates.

A typed time gets blanked out on save. The value didn't parse. Check the parsing table — anything unrecognised normalizes to null. If you're in strict() mode, an off-grid time is rejected by design (with a validation message when it bypasses the browser).

durationFrom() labels or defaultDuration() auto-fill aren't updating. Make the source field ->live() so its value propagates as it changes.

Translations

Every user-facing string — the "no matching time" hint, the strict-mode validation message, and the durationFrom duration words ("hour", "mins", "h", "m") — lives under the harvirsidhu-filament-timepicker namespace. Publish them to translate or override:

Then edit lang/vendor/filament-timepicker/<locale>/time-picker.php.

How it works under the hood

Curious or extending it? The design choices that matter:

• The text box is driven by a local Alpine string, never bound directly to Livewire. The canonical H:i value is written to the entangled state only when you commit (pick an option, press Enter, or blur with valid text). Typing never round-trips half-parsed text through the server, so the cursor never jumps.
• Parsing lives in two mirrored places — instantly in JavaScript for feedback, and authoritatively in PHP (TimeParser) on dehydration. The server's result is final: clean H:i/H:i:s or null.
• The Alpine component ships as a Filament asset and is lazy-loaded with x-load, so it costs nothing on pages that don't use the field.
• It implements the ARIA combobox/listbox pattern (role, aria-expanded, aria-activedescendant, aria-selected), so keyboard navigation is announced to screen readers.

Contributing & development

The compiled resources/js/dist/ file is committed — consumers don't build it. After changing the JS, rebuild, then in any consuming app re-run php artisan filament:assets to re-publish.

If you change a parsing rule, change it in both src/Support/TimeParser.php (PHP, authoritative) and resources/js/components/smart-time-picker.js (JS), and update both test suites — they're meant to stay in lockstep.

Credits

• harvirsidhu

License

The MIT License (MIT). See LICENSE.md.