Livewire Datepicker Laravel Package

Product Decisions This Supports

• Localization market entry (Iran/Persian-speaking users). This package is the fastest way to ship a compliant, Jalali-aware date input without building calendar conversion, RTL layout, and Persian locale strings in-house. It directly unblocks any feature requiring dates for a Persian-facing product: onboarding/birthdate forms, booking and scheduling, subscription and billing cycles, report date-range filters, and event management.
• Build vs. buy for date handling. Datepickers look trivial and are not: Hijri/Jalali conversion, leap-year edge cases, RTL, keyboard accessibility, and range/multi-select logic are all recurring sources of bugs. Adopting a component that bundles jalaali-js and wires to morilog/jalali on the PHP side removes a whole class of defect risk from the roadmap at near-zero cost.
• Storage-format decoupling. The export-calendar/export-format options let the product display Jalali while persisting ISO Gregorian dates. This is an architecture decision worth naming explicitly: it keeps the database portable, keeps reporting/BI tooling working on standard dates, and avoids a one-way-door schema decision later.
• Timeboxed scope decisions. Support for single, range, and multiple selection plus min/max/disabled dates covers most roadmap items (availability calendars, blackout dates, "pick up to N dates" flows) without a custom build. Features it supports natively can be scheduled with confidence; features it doesn't (recurring dates, time-of-day picking, timezones, business-day rules) should be explicitly scoped as separate work.
• Pilot-first rollout. Because adoption signal is essentially zero, the right product decision is a contained pilot (one admin form or filter bar) as a validation gate before wider rollout — this is a de-risking decision, not a technical one.

When to Consider This Package

Consider it when:

• The application is Laravel 11/12 (or 13 on the dedicated release line) on Livewire 3 or 4 — this is a hard prerequisite. Inertia/Vue/React stacks are out of scope; the component is a Blade/Alpine wrapper around wire:model.
• Persian/Jalali dates are a genuine user-facing requirement, and you need display-in-Jalali with Gregorian persistence.
• You want zero front-end build work: no npm install, no Vite entry, no jQuery — the bundled script loads with the component.
• You need one or more of: range selection, multi-select with a cap, min/max bounds, disabled dates, RTL, light/dark/auto theming, inline mode.
• You need server-side conversion helpers alongside the UI (jalali_to_gregorian / gregorian_to_jalali).
• The UI is form- or filter-oriented and can tolerate a component with thin docs and no community track record.

Look elsewhere when:

• Adoption risk matters. Zero stars, zero dependents, single-maintainer, README-plus-changelog-only maturity. Treat it as an unvetted dependency: pin the version, vendor-fork it or wrap it behind your own component, and assume you may own maintenance.
• You need time selection, timezones, or recurrence. Not in the feature set; bolting these on means fighting the component.
• You need holidays/business-day logic. Config has a holidays key explicitly "reserved for future use" — do not plan around it.
• Livewire 2 or older Laravel. The docs and changelog target Livewire 3+ and Laravel 11+; the Laravel 13 line also raises the PHP floor to 8.3. Version mismatch is the most common failure mode for small packages — verify composer.json constraints before writing code.
• You have strict vendor/security review. No security posture, release cadence, or issue history to evaluate; expect to justify the choice manually.
• A non-Persian datepicker is all you need. Use the established ecosystem option rather than adopting a niche package for a generic need.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can serve Persian-speaking users with correct, culturally expected date entry in days rather than weeks, at effectively no licensing cost (MIT). The package handles Jalali↔Gregorian conversion, right-to-left layout, accessibility, and date-range/multi-select behavior out of the box — work we would otherwise build, test, and maintain ourselves. It also lets us store standard Gregorian dates in the database, so our reporting and data tooling stay unchanged and we avoid a schema decision we can't easily reverse. The trade-off is maturity: it's a young, single-maintainer package with no adoption yet, so I recommend a scoped pilot on one non-critical screen, a pinned version, and a thin internal wrapper so we can swap it if it stalls. Risk is contained and reversible; the alternative is a custom build with ongoing ownership cost.

For engineering (the ask): Adopt behind a wrapper component (<x-app-datepicker>) rather than using <x-jalali-datepicker> directly across the codebase. Pilot on one admin form or report filter. Pin the version, commit the published config, and confirm the Livewire/Laravel/PHP constraint matrix against our stack before estimating. Normalize and validate server-side (Carbon::parse(...)->toDateString()) rather than trusting display formats, and always set wire:key when rendering pickers in loops. Budget a small spike to read src/ and resources/views/ since documentation is thin — and treat that spike as our real onboarding doc. If the pilot passes, expanding coverage is mostly template work, not integration work.