A text input with a <.calendar> in a panel underneath it. The input shows a formatted date you can type into; the form always posts ISO 8601.

Examples

<.date_picker name="due_on" label="Due date" value={~D[2026-03-14]} format="%d %b %Y" />

Wired to a form field, it takes its name, value, errors and label the same way <.field> does:

<.form for={@form} phx-change="validate" phx-submit="save">
  <.date_picker field={@form[:due_on]} label="Due date" min={Date.utc_today()} />
</.form>

Range mode posts from and to sub-fields, so params["stay"] comes back as %{"from" => "2026-03-10", "to" => "2026-03-17"}:

<.date_picker
  name="stay"
  mode="range"
  two_months
  min={Date.utc_today()}
  value={{~D[2026-03-10], ~D[2026-03-17]}}
/>

What gets posted

The visible input is display-only: it is not named, so it never posts. A hidden input carries the value in ISO 8601 (YYYY-MM-DD) whatever format you show, because a strftime string is for humans and a form value is for your changeset.

Parse on blur

You can type in the input. On blur (or Enter) the picker tries, in order:

1. Date.from_iso8601/1, so 2026-03-14 always works
2. a lenient parse of the configured format, so 14 Mar 2026 works when format is "%d %b %Y"

On success the hidden value and the calendar's month both move to the parsed date. On failure the input reverts to the last valid formatted value, so a half-typed date can never silently post as nothing. Enter commits the same way blur does, and when it lands a COMPLETE selection - both ends in range mode - it also closes the panel; a partial or failed parse keeps it open. Clicking a day keeps the same contract: the click that completes the selection (any single-mode click, a range's second end) closes the panel and hands focus back to the input; a range's anchor click keeps browsing. The calendar icon is a true toggle - it opens a closed panel and closes an open one.

While the panel is open, typing does not even wait for blur: the moment the text parses to a complete selection, the calendar pages to it and paints it, with the caret and your text left exactly where they are (14 Mar 2027 canonicalises to the configured format on blur or Enter, not mid-keystroke). Incomplete text does nothing - previews never revert. Server-owned pickers (on_select) keep the blur/Enter contract only, so your handler is never fed per-keystroke half-states.

One wiring requirement that bites: with on_month_change left nil, month navigation renders as patch links carrying month_param - which only pages if your LiveView actually handles that param in handle_params/3 and feeds it back through month. In a LiveView that ignores the param, prev/next do nothing and a typed far-away date cannot bring its month into view. Either handle the param, or pass on_month_change and assign the pushed month - the typed-date month jump works through whichever wiring you chose.

With on_select set the server owns the value, so a parsed date is pushed to you as that same event rather than written client-side - typing 12 Jun 1987 and clicking 12 June 1987 arrive at handle_event/3 identically. In range mode a typed range arrives as two events in reading order, exactly as two clicks would, so the handler you already have keeps working. Emptying the input pushes on_clear when you have wired one; without one there is nothing the picker can push, so the display reverts rather than sit there disagreeing with the value that will actually post.

LiveView and dead views

With on_select set, clicking a day pushes that event with the ISO date and your handle_event/3 owns the value. Without it, the PetalDatePicker hook writes the hidden input itself and dispatches input/change, which is enough for a plain form post or a phx-change form. The panel opens and closes with Phoenix.LiveView.JS either way: Escape closes it and returns focus to the input, and clicking outside dismisses it.