Phoenix implementation of Zag.js Date Picker.

Anatomy

Basic Usage

<.date_picker>
  <:label>Select a date</:label>
  <:trigger>
    <.heroicon name="hero-calendar" />
  </:trigger>
         <:prev_trigger>
        <.heroicon name="hero-chevron-left" class="icon" />
      </:prev_trigger>
      <:next_trigger>
        <.heroicon name="hero-chevron-right" class="icon" />
      </:next_trigger>
</.date_picker>

Form

When using with Phoenix forms, set the form id in to_form/2 (for example to_form(changeset, as: :name, id: "my-form")) and use <.form for={@form}>.

For cross-cutting invalid styling and error presentation, see the Forms guide. Pass invalid={Corex.FormField.invalid?(@form[:date])} when you want alert borders after validation.

Wire format vs domain types

The component and LiveView events use ISO-8601 strings (value, on_value_change, hidden inputs). Ecto schemas should use :date and {:array, :date}. After cast, work with %Date{} in application code.

Use cast_params/2 in handle_event to normalize on_value_change or form params before cast/3:

def handle_event("date_changed", %{"value" => value}, socket) do
  params = Corex.DatePicker.cast_params("single", %{"value" => value})

  changeset =
    MyApp.Form.DateForm.changeset_validate(%MyApp.Form.DateForm{}, params)
    |> Map.put(:action, :validate)

  {:noreply, assign(socket, :form, to_form(changeset, action: :validate))}
end

Controller

Build the form from an Ecto changeset:

def form_page(conn, _params) do
  form =
    %MyApp.Form.DateForm{}
    |> MyApp.Form.DateForm.changeset(%{})
    |> Phoenix.Component.to_form(as: :date_form, id: "date-form")
  render(conn, :form_page, form: form)
end

<.form :let={f} for={@form} action={@action} method="post">
  <.date_picker
    field={f[:date]}
    class="date-picker"
    translation={%Corex.DatePicker.Translation{
      open_calendar: "Select date",
      close_calendar: "Select date",
      input: "Select date"
    }}
  >
    <:label>Date</:label>
    <:trigger>
      <.heroicon name="hero-calendar" class="icon" />
    </:trigger>
    <:prev_trigger>
      <.heroicon name="hero-chevron-left" class="icon" />
    </:prev_trigger>
    <:next_trigger>
      <.heroicon name="hero-chevron-right" class="icon" />
    </:next_trigger>
    <:error :let={msg}>
      <.heroicon name="hero-exclamation-circle" class="icon" />
      {msg}
    </:error>
  </.date_picker>
  <button type="submit">Submit</button>
</.form>

Live View

Prefer building the form from an Ecto changeset (see "With Ecto changeset" below). Use phx-change on the form so params stay in sync after validation.

With Ecto changeset

Use field={@form[:birth_date]} inside <.form for={@form}>. The component resyncs from the server value on patch without controlled.

First create your schema and changeset:

defmodule MyApp.Accounts.User do
  use Ecto.Schema
  import Ecto.Changeset

  schema "users" do
    field :name, :string
    field :birth_date, :date
    timestamps(type: :utc_datetime)
  end

  def changeset(user, attrs) do
    user
    |> cast(attrs, [:name, :birth_date])
    |> validate_required([:name, :birth_date])
  end
end

defmodule MyAppWeb.UserLive do
  use MyAppWeb, :live_view
  alias MyApp.Accounts.User

  def mount(_params, _session, socket) do
    {:ok, assign(socket, :form, to_form(User.changeset(%User{}, %{})))}
  end

  def handle_event("validate", %{"user" => user_params}, socket) do
    changeset = User.changeset(%User{}, user_params)
    {:noreply, assign(socket, form: to_form(changeset, action: :validate))}
  end

  def render(assigns) do
    ~H"""
    <.form for={@form} phx-change="validate">
      <.date_picker field={@form[:birth_date]} class="date-picker">
        <:label>Birth date</:label>
        <:trigger>
          <.heroicon name="hero-calendar" class="icon" />
        </:trigger>
        <:prev_trigger>
          <.heroicon name="hero-chevron-left" class="icon" />
        </:prev_trigger>
        <:next_trigger>
          <.heroicon name="hero-chevron-right" class="icon" />
        </:next_trigger>
        <:error :let={msg}>
          <.heroicon name="hero-exclamation-circle" class="icon" />
          {msg}
        </:error>
      </.date_picker>
    </.form>
    """
  end
end

API

Requires a stable id on <.date_picker>.

Events

Pick an event name and pass it to on_* on <.date_picker>.

Server events

on_value_change

<.date_picker
  class="date-picker"
  controlled
  value={@date_value}
  on_value_change="date_changed"
>
  <:label>Select a date</:label>
  <:trigger><.heroicon name="hero-calendar" class="icon" /></:trigger>
  <:prev_trigger><.heroicon name="hero-chevron-left" class="icon" /></:prev_trigger>
  <:next_trigger><.heroicon name="hero-chevron-right" class="icon" /></:next_trigger>
</.date_picker>

def handle_event("date_changed", %{"value" => value}, socket) do
  params = Corex.DatePicker.cast_params("single", %{"value" => value})
  changeset = MyApp.Form.DateForm.changeset_validate(%MyApp.Form.DateForm{}, params)
  {:noreply, assign(socket, :form, to_form(changeset, action: :validate))}
end

Event value is always an ISO string (comma-joined for multiple/range). Use cast_params/2 before Ecto cast/3.

Client events

Patterns

Controlled

Set controlled, bind value, and handle on_value_change. Pass ISO-8601 strings or Date.to_iso8601/1 for a Date assign.

<.date_picker
  class="date-picker"
  controlled
  value={@due && Date.to_iso8601(@due)}
  on_value_change="date_changed"
>
  <:label>Due</:label>
  <:trigger><.heroicon name="hero-calendar" class="icon" /></:trigger>
  <:prev_trigger><.heroicon name="hero-chevron-left" class="icon" /></:prev_trigger>
  <:next_trigger><.heroicon name="hero-chevron-right" class="icon" /></:next_trigger>
</.date_picker>

assign(socket, :due, ~D[2024-01-15])

Style

Use data attributes to target elements:

[data-scope="date-picker"][data-part="root"] {}
[data-scope="date-picker"][data-part="label"] {}
[data-scope="date-picker"][data-part="control"] {}
[data-scope="date-picker"][data-part="input"] {}
[data-scope="date-picker"][data-part="trigger"] {}
[data-scope="date-picker"][data-part="positioner"] {}
[data-scope="date-picker"][data-part="content"] {}

@import "../corex/main.css";
@import "../corex/tokens/themes/neo/light.css";
@import "../corex/components/date-picker.css";

Stack modifiers on the host (class on <.date_picker>).

Color

Size

In selection_mode "range", the control shows two fields with side labels from translation (From / To by default, via gettext). In "multiple", a single field shows a comma‑separated list of the formatted selected dates. Use max_selected_dates to cap how many days can be selected in multiple mode; omit for no cap.

Localization and translation

Pass translation={%Corex.DatePicker.Translation{}} to override any string. Omitted fields use gettext defaults (see Corex.DatePicker.Translation).