A date picker component that provides calendar-based date selection with support for time picking and date ranges.

Usage

The component provides three specialized functions to handle different date selection needs. Here are examples of each use case:

<!-- Single date selection -->
<.date_picker
  name="appointment"
  label="Appointment Date"
/>

<!-- Date and time selection -->
<.date_time_picker
  name="meeting"
  label="Meeting Time"
  time_format="12"  # or "24" for 24-hour format
/>

<!-- Date range selection -->
<.date_range_picker
  start_name="check_in"
  end_name="check_out"
  label="Stay Period"
/>

Like all other form components, the date picker supports various labeling options to provide context and guidance to users:

<.date_picker
  name="appointment"
  label="Appointment Date"
  sublabel="Required"
  description="Choose when you'd like to schedule your consultation"
  help_text="Our office is open Monday through Friday, 9 AM to 5 PM"
/>

Date Range Constraints

The date picker supports limiting the selectable dates through the min and max attributes. Both attributes expect an Elixir Date struct and provide client-side validation only. For security purposes, you should always implement corresponding backend validations, typically through Ecto changesets.

Here's an example that limits date selection to the next 30 days:

<.date_picker
  field={f[:deadline]}
  label="Project Deadline"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 30)}
/>

You can also use date literals with the ~D sigil for fixed dates:

<.date_picker
  name="birth_date"
  label="Birth Date"
  min={~D[1900-01-01]}
  max={Date.utc_today()}
/>

When date constraints are set, the component:

• Disables and visually styles dates outside the allowed range
• Prevents keyboard navigation to disabled dates
• Automatically disables month/year navigation buttons when the visible month would not show any selectable dates
• Ensures the calendar opens to a month containing selectable dates, even if the current month is outside the allowed range
• Maintains the constraints when switching between months or years
• Clears the selection if a previously selected date becomes invalid due to dynamically changed constraints

Multiple Date Selection

The date picker supports selecting multiple dates through the multiple attribute. This mode is particularly useful for scenarios like scheduling recurring events, selecting holiday dates, or planning multiple appointments:

<.date_picker
  field={f[:holidays]}
  label="Company Holidays"
  multiple
  description="Select all company holidays for the year"
  help_text="Click dates to toggle selection"
/>

When multiple date selection is enabled:

• The calendar remains open after each selection to facilitate choosing multiple dates
• Each selected date is visually highlighted in the calendar
• Clicking a selected date deselects it
• The toggle button displays "X dates selected" when more than one date is chosen
• Time picker integration is not supported (see Time Picker Integration)
• Auto-close mode is not supported (see Closing Strategies)

# When dates are selected
%{
  "date_form" => %{
    "holidays" => ["2025-05-15", "2025-05-14", "2025-05-22"]
  }
}

# When all dates are deselected (hidden input provides the empty value)
%{
  "date_form" => %{
    "holidays" => [""]  # Instead of field being omitted entirely
  }
}

Date Formatting

The date picker uses Elixir's strftime under the hood to format dates. Control how dates are displayed using the display_format attribute:

<.date_picker
  field={f[:date]}
  label="Date"
  display_format="%B %-d, %Y"  # Displays as "January 1, 2024"
/>

Common date format patterns:

• "%Y-%m-%d": ISO format (2024-01-01)
• "%b %-d, %Y": Short month (Jan 1, 2024)
• "%B %-d, %Y": Full month (January 1, 2024)
• "%d/%m/%Y": European format (01/01/2024)
• "%m/%d/%Y": US format (01/01/2024)

When using the date_time_picker/1 component, you should include time format patterns in your display format. Here are some common datetime patterns:

<.date_time_picker
  field={f[:appointment]}
  label="Appointment"
  time_format="12"
  display_format="%B %-d, %Y at %I:%M %p"  # January 1, 2024 at 02:30 PM
/>

<.date_time_picker
  field={f[:meeting]}
  label="Meeting"
  time_format="24"
  display_format="%Y-%m-%d %H:%M"  # 2024-01-01 14:30
/>

Common datetime format patterns:

• "%Y-%m-%d %H:%M:%S": ISO format with 24h time (2024-01-01 14:30:00)
• "%B %-d, %Y at %I:%M %p": Full month with 12h time (January 1, 2024 at 02:30 PM)
• "%d/%m/%Y %H:%M": European format with 24h time (01/01/2024 14:30)
• "%m/%d/%Y %I:%M %p": US format with 12h time (01/01/2024 02:30 PM)
• "%a, %b %-d at %I:%M %p": Short format (Mon, Jan 1 at 02:30 PM)

Time format specifiers:

• %H: 24-hour format (00-23)
• %I: 12-hour format (01-12)
• %M: Minutes (00-59)
• %S: Seconds (00-59)
• %p: AM/PM indicator

Week Start Configuration

The date picker allows customizing which day of the week appears in the first column through the week_start attribute. This is particularly useful for adapting to different cultural preferences, as some regions start their weeks on Sunday while others prefer Monday:

<.date_picker
  field={f[:date]}
  label="Date"
  week_start={1}  # Week starts on Monday
/>

The week_start attribute accepts a number from 0 to 6, where each number maps to a day:

When you change the week start day:

• The calendar grid adjusts to show the specified day in the first column
• All other days shift accordingly while maintaining their order
• Week-based keyboard navigation (e.g., up/down arrows) adapts to the new week structure
• The calendar maintains the new week start even when navigating between months

Date Time Picker

The date_time_picker/1 function combines date selection with precise time input, supporting both 12-hour and 24-hour time formats. This is particularly useful for scheduling appointments, meetings, or any event that requires specific timing:

<.date_time_picker
  field={f[:appointment]}
  label="Appointment Time"
  time_format="12"
  display_format="%B %-d, %Y at %I:%M %p"
/>

The time input interface appears below the calendar and includes hours and minutes fields. When using 12-hour format (time_format="12"), an AM/PM selector is also displayed. The component handles time entry through both keyboard input and increment/decrement controls:

<!-- 24-hour format with custom display -->
<.date_time_picker
  field={f[:meeting_start]}
  label="Meeting Start"
  time_format="24"
  display_format="%d/%m/%Y %H:%M"
/>

<!-- With form integration and validation -->
<.form :let={f} for={@changeset} phx-change="validate">
  <.date_time_picker
    field={f[:scheduled_at]}
    label="Schedule For"
    time_format="12"
    min={~D[2025-02-01]}
    max={~D[2025-03-31]}
  />
</.form>

When working with the date time picker, keep in mind:

The field value must be a NaiveDateTime or DateTime struct. Using a Date struct will raise runtime errors since it cannot store time information. For example, in your schema:

schema "appointments" do
  field :scheduled_at, :naive_datetime
  # ...
end

The component provides a natural interface for time selection:

• Direct keyboard input for quick value entry
• Up/down arrow keys to increment/decrement values
• Automatic value constraints (hours: 0-23 or 1-12, minutes: 0-59)
• Tab navigation between hour, minute, and AM/PM fields
• AM/PM toggle with 'a' and 'p' keys in 12-hour mode
• Enter key to confirm and close the date time picker

Date Range Picker

The date_range_picker/1 function provides a specialized interface for selecting date ranges, making it ideal for booking systems, reporting tools, or any feature requiring start and end dates. The component offers both form-integrated and standalone usage:

<.form :let={f} for={@changeset} phx-change="validate">
  <.date_range_picker
    start_field={f[:start_date]}
    end_field={f[:end_date]}
    label="Booking Period"
    min={Date.utc_today()}
    max={Date.add(Date.utc_today(), 90)}
  />
</.form>

Unlike the single date picker, the range picker handles two distinct fields (start and end dates) individually. This means each date has its own field in your schema and form, providing more flexibility for validation and data handling. The component provides visual feedback during selection, highlighting the range as users make their choices. When a date is selected, it becomes either the start or end date based on its position relative to any existing selection. The calendar remains open until both dates are chosen, allowing users to adjust their selection with immediate visual feedback.

The component supports several intuitive interaction patterns:

• Click two different dates to select a range
• Click the same date twice to create a single-day range
• Click a date within an existing range to shrink the range
• Click outside an existing range to expand it
• Click a selected date to clear the selection and start over

For standalone usage without form integration, use the name-based attributes:

<.date_range_picker
  start_name="check_in"
  end_name="check_out"
  start_value={@check_in}
  end_value={@check_out}
  label="Stay Period"
  description="Select your check-in and check-out dates"
/>

The component handles various selection patterns intuitively:

<.date_range_picker
  start_field={f[:period_start]}
  end_field={f[:period_end]}
  label="Report Period"
  display_format="%B %-d, %Y"  # January 1, 2024
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 365)}
  help_text="Select dates within the current year"
/>

Form submissions include both start and end dates as separate fields, making it straightforward to handle in your LiveView:

def handle_event("validate", %{"booking" => params}, socket) do
  changeset =
    %Booking{}
    |> Booking.changeset(params)
    |> Map.put(:action, :validate)

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

# In your schema
schema "bookings" do
  field :start_date, :date
  field :end_date, :date
  timestamps()
end

def changeset(booking, attrs) do
  booking
  |> cast(attrs, [:start_date, :end_date])
  |> validate_required([:start_date, :end_date])
  |> validate_start_before_end()
end

defp validate_start_before_end(changeset) do
  case {get_field(changeset, :start_date), get_field(changeset, :end_date)} do
    {start_date, end_date} when not is_nil(start_date) and not is_nil(end_date) ->
      if Date.compare(end_date, start_date) == :lt do
        add_error(changeset, :end_date, "must be after start date")
      else
        changeset
      end

    _ ->
      changeset
  end
end

The component automatically sorts the selected dates, ensuring that the earlier date becomes the start date regardless of selection order. This behavior, combined with the visual feedback and intuitive interaction patterns, creates a natural and error-resistant date range selection experience.

Closing Strategies

The date picker provides three distinct modes for handling when the calendar closes and when changes are confirmed. Each mode serves different use cases and can be controlled through the close attribute.

Auto Mode (default)

The default "auto" mode provides the most streamlined experience for single date selection. In this mode, the calendar closes immediately after a date is selected, and change events are emitted as soon as the selection is made. This is ideal for simple date picking scenarios where immediate feedback is desired:

<.date_picker
  field={f[:date]}
  close="auto"     <!-- Default behavior -->
/>

The component automatically falls back to manual mode when using features that require multiple interactions, such as time picker integration, range selection, or multiple date selection.

Manual Mode

The "manual" mode keeps the calendar open after selection, offering more flexibility for users who need to compare dates or make multiple adjustments. While the calendar stays open, change events are still emitted immediately as selections change:

<.date_picker
  field={f[:date]}
  close="manual"
/>

Users can explicitly close the calendar through standard interactions: pressing the Escape key, clicking outside the calendar, or clicking the toggle button.

Confirm Mode

The "confirm" mode adds an explicit confirmation step, making it ideal for scenarios where accuracy is crucial. This mode introduces Cancel and Confirm buttons at the bottom of the calendar and treats changes as "pending" until explicitly confirmed:

<.date_picker
  field={f[:date]}
  close="confirm"
/>

In confirm mode, the calendar stays open until explicitly confirmed or cancelled, and change events are only emitted after clicking the confirm button. If the user cancels or closes the calendar, the previous selection is restored, ensuring data integrity.

Navigation Modes

The date picker provides three navigation modes that determine how users can move between months and years. Each mode is configured through the navigation attribute.

Default Mode

The default mode offers a simple and clean interface focused on month-to-month navigation. It displays the current month and year as text, with arrow buttons on either side for moving to the previous or next month.

<.date_picker field={f[:date]} navigation="default" />

Extended Mode

Extended mode enhances the default navigation by adding year navigation arrows alongside the month arrows. This creates a more efficient way to navigate through larger time spans while maintaining the familiar arrow-based interaction.

<.date_picker field={f[:date]} navigation="extended" />

Select Mode

Select mode transforms the navigation interface by combining month arrows with dropdown menus for both month and year selection. The dropdowns provide direct access to any month or year within the allowed range.

<.date_picker field={f[:date]} navigation="select" />

Form Integration

The date picker component provides robust form integration through two approaches: using Phoenix form fields (recommended) or using standalone name attributes. Each approach supports single dates, multiple dates, and date ranges.

Using with Phoenix Forms (Recommended)

Use the field attribute to bind the date picker to a form field:

<.form :let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.date_picker
    field={f[:appointment_date]}
    label="Appointment Date"
    min={Date.utc_today()}
    max={Date.add(Date.utc_today(), 30)}
  />
</.form>

Using the field attribute provides:

• Automatic value handling from form data
• Error handling and validation messages
• Form submission with correct field names
• Integration with changesets
• ID generation for accessibility
• Proper type conversion between form data and Elixir date types
• Nested form data handling

Here's a complete example showing different date field types and validations:

defmodule MyApp.Booking do
  use Ecto.Schema
  import Ecto.Changeset

  schema "bookings" do
    # Single date field
    field :appointment_date, :date

    # Date with time
    field :meeting_datetime, :naive_datetime

    # Multiple dates
    field :blocked_dates, {:array, :date}

    # Date range
    field :start_date, :date
    field :end_date, :date

    timestamps()
  end

  def changeset(booking, attrs) do
    booking
    |> cast(attrs, [:appointment_date, :meeting_datetime, :blocked_dates, :start_date, :end_date])
    |> validate_required([:appointment_date])
    |> validate_future_date(:appointment_date)
    |> validate_date_range()
  end

  # Custom validation for future dates
  defp validate_future_date(changeset, field) do
    validate_change(changeset, field, fn _, date ->
      if Date.compare(date, Date.utc_today()) == :lt do
        [{field, "must be in the future"}]
      else
        []
      end
    end)
  end

  # Validate that end_date comes after start_date
  defp validate_date_range(changeset) do
    case {get_field(changeset, :start_date), get_field(changeset, :end_date)} do
      {start_date, end_date} when not is_nil(start_date) and not is_nil(end_date) ->
        if Date.compare(end_date, start_date) == :lt do
          add_error(changeset, :end_date, "must be after start date")
        else
          changeset
        end

      _ ->
        changeset
    end
  end
end

# In your LiveView
def mount(_params, _session, socket) do
  changeset = Booking.changeset(%Booking{}, %{})
  {:ok, assign(socket, form: to_form(changeset))}
end

def render(assigns) do
  ~H"""
  <.form :let={f} for={@form} phx-change="validate">
    <.date_picker
      field={f[:appointment_date]}
      label="Appointment Date"
      min={Date.utc_today()}
    />

    <.date_time_picker
      field={f[:meeting_datetime]}
      label="Meeting Time"
      time_format="12"
    />

    <.date_picker
      field={f[:blocked_dates]}
      label="Blocked Dates"
      multiple
      help_text="Select multiple dates that should be unavailable"
    />

    <.date_range_picker
      start_field={f[:start_date]}
      end_field={f[:end_date]}
      label="Booking Period"
    />
  </.form>
  """
end

def handle_event("validate", %{"booking" => params}, socket) do
  changeset =
    %Booking{}
    |> Booking.changeset(params)
    |> Map.put(:action, :validate)

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

Using Standalone Date Pickers

For simpler cases or when not using Phoenix forms, use the name attribute:

<!-- Single date -->
<.date_picker
  name="filter_date"
  label="Filter By Date"
  value={@selected_date}
/>

<!-- Multiple dates -->
<.date_picker
  name="holiday_dates[]"
  label="Holiday Dates"
  multiple
  value={@selected_dates}
/>

<!-- Date range -->
<.date_range_picker
  start_name="check_in"
  end_name="check_out"
  start_value={@check_in}
  end_value={@check_out}
  label="Stay Period"
/>

<!-- Date with time -->
<.date_time_picker
  name="event_time"
  label="Event Time"
  time_format="24"
  value={@event_datetime}
/>

When using standalone date pickers:

• The name attribute determines the form field name
• Values are managed through the value attribute (or start_value/end_value for ranges)
• For multiple selection, append [] to the name attribute
• Errors are passed via the errors attribute
• Values are submitted in ISO 8601 format (YYYY-MM-DD or YYYY-MM-DD HH:mm:ss)
• For date ranges, use start_name and end_name to specify field names

Keyboard Support

The component provides comprehensive keyboard navigation:

When time picker is enabled:

The component implements a focus trap when open, ensuring keyboard navigation stays within the calendar.