codingwithrk / nativephp-datetime-picker

v1.0.0 2026-09-09 19:15 UTC

Requires

• php: ^8.2
• nativephp/mobile: ^3.0 || ^4.0

Requires (Dev)

• pestphp/pest: ^3.0

MIT

• codingwithrk

• mobile
• datetime
• date-picker
• datetime-picker
• nativephp
• nativephp-plugin
• time-picker

Published on Packagist.org on 2026-09-09 19:16 UTC

README

Native date, time and datetime picker for NativePHP Mobile.

• 📱 iOS — wheel-style UIDatePicker in a bottom sheet
• 🤖 Android — platform DatePickerDialog / TimePickerDialog (works on any app theme, no Material 3 dependency)
• 🧩 Livewire and Inertia (Vue / React) support
• 🔢 date, time, time12h and datetime modes
• 📐 min / max bounds, initial value, custom title, 12h / 24h, locale hint
• ✅ Compatible with nativephp/mobile v3 and v4

Installation

composer require codingwithrk/nativephp-datetime-picker

php artisan native:plugin:register codingwithrk/nativephp-datetime-picker
php artisan native:run

For local development, add a path repository to your app's composer.json:

{
    "repositories": [
        { "type": "path", "url": "packages/codingwithrk/nativephp-datetime-picker" }
    ]
}

How it works

The picker is modal and asynchronous. Calling it opens the native picker and immediately returns a request id (a string). The value the user selects is delivered later as a native event. Always pair a call with an event listener.

Usage (PHP / Livewire)

use Livewire\Component;
use Native\Mobile\Attributes\OnNative;
use Illuminate\Support\Carbon;
use Codingwithrk\NativephpDatetimePicker\Facades\DateTimePicker;
use Codingwithrk\NativephpDatetimePicker\Events\DateTimePickerConfirmed;
use Codingwithrk\NativephpDatetimePicker\Events\DateTimePickerCancelled;

class BookingForm extends Component
{
    public ?string $startsAt = null;

    public function pickStart(): void
    {
        DateTimePicker::make()
            ->dateTime()
            ->min(now())
            ->max(now()->addMonths(6))
            ->current(now())
            ->title('When does it start?')
            ->use12h()
            ->show();
    }

    #[OnNative(DateTimePickerConfirmed::class)]
    public function onPicked($value, $mode, $timestamp = 0, $id = null): void
    {
        $this->startsAt = Carbon::parse($value)->toDateTimeString();
    }

    #[OnNative(DateTimePickerCancelled::class)]
    public function onCancelled($id = null): void
    {
        //
    }
}

Quick helpers

use Codingwithrk\NativephpDatetimePicker\Facades\DateTimePicker;

DateTimePicker::date();            // date only
DateTimePicker::time();            // time, 24-hour
DateTimePicker::time12h();         // time, AM/PM
DateTimePicker::dateTime(now());   // date + time

Usage (JavaScript / Inertia + Vue / React)

import { dateTimePicker } from '@codingwithrk/nativephp-datetime-picker';

// open the picker
await dateTimePicker.make()
    .dateTime()
    .min(new Date())
    .current(new Date())
    .use12h()
    .show();

// handle the result
const unsubscribe = dateTimePicker.onConfirm(({ id, value, mode, timestamp }) => {
    console.log('picked', value); // "2026-09-09T14:30:00"
});

dateTimePicker.onCancel(({ id }) => console.log('cancelled'));

The JS event helpers subscribe to the native-event DOM event that NativePHP Mobile dispatches on document (the same channel window.Native.on() uses), filtering by event class. In a Livewire app, prefer the #[OnNative] attribute shown above.

API

Builder — DateTimePicker::make()

Method	Description
mode('date'|'time'|'datetime')	Set the picker mode
date()	Date-only mode
time(bool $use24h = true)	Time-only mode
time12h()	Time-only, AM/PM clock
dateTime()	Combined date + time
min($date)	Earliest selectable moment (DateTimeInterface or string)
max($date)	Latest selectable moment
current($date) / initial($date)	Value the picker opens on (default: now)
title(?string $title)	Heading shown above the wheels
use24h(bool $value = true) / use12h()	Clock format for time modes
locale(?string $locale)	BCP-47 locale hint (en, de, ar, …)
withChangeEvents(bool $value = true)	Stream DateTimePickerChanged while scrolling (iOS only)
id(string $id)	Provide your own correlation id
show(): string	Present the picker; returns the request id

Convenience methods on the facade

DateTimePicker::date(), ::time(), ::time12h(), ::dateTime() — each accepts an optional initial value and returns the request id.

Events

Event	Payload
Events\DateTimePickerConfirmed	string $value, string $mode, int $timestamp, ?string $id
Events\DateTimePickerCancelled	?string $id
Events\DateTimePickerChanged	same as Confirmed — iOS only, opt-in via withChangeEvents()

$value is a local ISO-8601 string with no timezone (Y-m-d\TH:i:s). $timestamp is milliseconds since the Unix epoch. DateTimePickerConfirmed / DateTimePickerChanged expose a date() helper returning a Carbon instance.

Permissions

None.

Platform notes

• Android uses the framework date/time dialogs, so there is no Material 3 requirement. datetime mode chains a date dialog into a time dialog; cancelling either emits DateTimePickerCancelled.
• Android dialogs cannot report an intermediate value — withChangeEvents() has no effect there.
• iOS presents a .wheels UIDatePicker in a medium bottom sheet. Swipe-to-dismiss and tap-outside both count as cancel.

Testing

composer test

License

MIT — see LICENSE.