A date picker component with calendar-based date selection and time support.

The date picker component provides calendar-based date selection with support for single dates, multiple dates, and date ranges. It includes time picking capabilities, configurable sizing, and affix slots for UI customization.

Basic Usage

The component provides three functions for different date selection modes:

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

<!-- Date and time selection -->
<.date_time_picker
  name="meeting"
  label="Meeting Time"
  time_format="12"
  placeholder="Select date and time"
/>

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

Common Examples

Examples for typical use cases:

<!-- Simple appointment booking -->
<.date_picker
  name="appointment"
  label="Appointment Date"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 60)}
  placeholder="Select your appointment date"
/>

<!-- Hotel booking with date range -->
<.date_range_picker
  start_name="check_in"
  end_name="check_out"
  label="Stay Duration"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 365)}
  placeholder="Select your dates"
/>

<!-- Meeting scheduler with time -->
<.date_time_picker
  name="meeting"
  label="Meeting Schedule"
  time_format="12"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 30)}
  placeholder="Choose meeting time"
/>

Size Variants

Five size variants are available:

<.date_picker name="xs" size="xs" label="Compact Date" placeholder="Extra small" />
<.date_picker name="sm" size="sm" label="Small Date" placeholder="Small" />
<.date_picker name="md" size="md" label="Standard Date" placeholder="Medium (Default)" />
<.date_picker name="lg" size="lg" label="Prominent Date" placeholder="Large" />
<.date_picker name="xl" size="xl" label="Hero Date" placeholder="Extra large" />

Size variants adjust height, padding, font size, and icon dimensions:

• "xs" (h-7): Compact layouts, dashboard widgets
• "sm" (h-8): Secondary inputs, sidebar forms
• "md" (h-9): Default size - standard applications
• "lg" (h-10): Prominent inputs, primary actions
• "xl" (h-11): Hero sections, landing pages

Context-Specific Sizing

<!-- Dashboard widget - compact -->
<.date_picker
  name="dashboard_filter"
  size="xs"
  label="Filter Date"
  placeholder="Filter by date..."
/>

<!-- Main form - standard -->
<.date_picker
  name="main_date"
  size="md"
  label="Event Date"
  placeholder="Choose event date..."
/>

<!-- Hero section - prominent -->
<.date_picker
  name="hero_date"
  size="xl"
  label="Launch Date"
  placeholder="When do you want to launch?"
/>

Labels and Descriptions

Configure labels and descriptions using available attributes:

<!-- Complete labeling example -->
<.date_picker
  name="event_date"
  label="Event Date"
  sublabel="Required"
  description="Choose when your event will take place"
  help_text="Events can be scheduled up to 6 months in advance"
  placeholder="Select event date"
/>

Real-World Labeling Scenarios

<!-- Professional appointment booking -->
<.date_picker
  name="appointment_date"
  label="Appointment Date"
  description="Select your preferred consultation date"
  help_text="Available Monday-Friday, 9 AM to 5 PM"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 60)}
  placeholder="Choose your appointment date"
/>

<!-- Project management deadline -->
<.date_picker
  name="project_deadline"
  label="Project Deadline"
  sublabel="Required"
  description="When should this project be completed?"
  help_text="Deadlines must be at least 1 day in the future"
  min={Date.add(Date.utc_today(), 1)}
  max={Date.add(Date.utc_today(), 90)}
  placeholder="Set project deadline"
/>

<!-- User profile information -->
<.date_picker
  name="birth_date"
  label="Date of Birth"
  description="We use this to verify your age"
  help_text="Your information is kept private and secure"
  min={~D[1900-01-01]}
  max={Date.utc_today()}
  navigation="select"
  placeholder="Enter your birth date"
/>

Inner Affixes

Add content inside the date picker's border using inner affix slots. Used for icons, status indicators, and visual elements:

<!-- Standard calendar icon -->
<.date_picker name="appointment" label="Appointment Date" placeholder="Select date">
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
</.date_picker>

<!-- Status indicators with dual affixes -->
<.date_picker name="event_date" label="Event Date" placeholder="Event date">
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
  <:inner_suffix>
    <.icon name="hero-check-circle" class="icon text-green-500!" />
  </:inner_suffix>
</.date_picker>

Advanced Inner Affix Patterns

<!-- Booking system with validation -->
<.date_picker name="check_in" label="Check-in Date" placeholder="Select check-in">
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
  <:inner_suffix>
    <.icon name="hero-check-circle" class="icon text-green-500!" />
  </:inner_suffix>
</.date_picker>

<!-- Urgent deadline with warning indicators -->
<.date_picker name="urgent_deadline" label="Urgent Deadline" placeholder="Set deadline">
  <:inner_prefix>
    <.icon name="hero-clock" class="icon" />
  </:inner_prefix>
  <:inner_suffix>
    <.icon name="hero-exclamation-triangle" class="icon text-red-500!" />
  </:inner_suffix>
</.date_picker>

<!-- Size-matched icons for different variants -->
<.date_picker name="small_with_icon" size="sm" label="Small Date" placeholder="Small">
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
</.date_picker>

<.date_picker name="large_with_icon" size="lg" label="Large Date" placeholder="Large">
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
</.date_picker>

Outer Affixes

Place content outside the date picker's border using outer affix slots. Used for buttons, labels, and interactive elements:

<!-- Simple text prefix -->
<.date_picker name="filtered" label="Due Date" placeholder="Select date">
  <:outer_prefix class="px-3 text-foreground-soft">Due:</:outer_prefix>
</.date_picker>

<!-- Action button integration -->
<.date_picker name="with_action" label="Reminder Date" placeholder="Select date">
  <:outer_suffix>
    <.button size="md">Set Reminder</.button>
  </:outer_suffix>
</.date_picker>

Complete Affix Compositions

<!-- Full-featured booking interface -->
<.date_picker name="appointment" label="Appointment" placeholder="Select appointment">
  <:outer_prefix class="px-2">Book</:outer_prefix>
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
  <:inner_suffix>
    <.icon name="hero-clock" class="icon" />
  </:inner_suffix>
  <:outer_suffix>
    <.button size="md">Confirm</.button>
  </:outer_suffix>
</.date_picker>

<!-- Hotel reservation system -->
<.date_range_picker
  start_name="check_in"
  end_name="check_out"
  label="Stay Duration"
  placeholder="Select dates"
>
  <:outer_prefix class="px-3">Stay:</:outer_prefix>
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
    <.button size="md">Check Availability</.button>
  </:outer_suffix>
</.date_range_picker>

Size Matching with Affixes

When using buttons or components within affix slots, match their size attribute to the date picker's size for proper visual alignment:

<.date_picker name="example" size="lg" label="Large Date">
  <:outer_suffix>
    <.button size="lg">Action</.button>  <!-- Matches date picker size -->
  </:outer_suffix>
</.date_picker>

Date Constraints and Validation

Control selectable dates using min and max attributes. These provide client-side validation only - always implement corresponding server-side validation for security:

Basic Constraint Patterns

<!-- Future dates only -->
<.date_picker
  name="future_only"
  label="Future Dates Only"
  min={Date.utc_today()}
  description="Cannot select past dates"
  placeholder="Select future date"
/>

<!-- Specific time window -->
<.date_picker
  name="deadline"
  label="Project Deadline"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 30)}
  description="Select within next 30 days"
  placeholder="Choose deadline"
/>

Business Logic Constraints

<!-- Appointment booking (business hours consideration) -->
<.date_picker
  name="appointment_date"
  label="Appointment Date"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 60)}
  description="Appointments available for the next 2 months"
  help_text="Monday-Friday, 9 AM to 5 PM"
  placeholder="Select appointment date"
/>

<!-- Event planning (advance notice required) -->
<.date_picker
  name="event_date"
  label="Event Date"
  min={Date.add(Date.utc_today(), 90)}
  max={Date.add(Date.utc_today(), 180)}
  description="Events must be planned 3-6 months ahead"
  placeholder="Choose event date"
/>

<!-- Birth date with reasonable bounds -->
<.date_picker
  name="birth_date"
  label="Date of Birth"
  min={~D[1900-01-01]}
  max={Date.utc_today()}
  navigation="select"
  description="Enter your date of birth"
  placeholder="Select birth date"
/>

Constraint Behavior

When constraints are applied, the component automatically:

• Disables and visually styles dates outside the allowed range
• Prevents keyboard navigation to disabled dates
• Disables navigation buttons when the target month contains no selectable dates
• Opens the calendar to a month containing valid dates
• Maintains constraints across month/year navigation
• Clears invalid selections when constraints change dynamically

def changeset(appointment, attrs) do
  appointment
  |> cast(attrs, [:date])
  |> validate_future_date(:date)
end

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

Multiple Date Selection

Enable multiple date selection using the multiple attribute. Used for scheduling recurring events, selecting holidays, or planning multiple appointments:

<!-- Basic multiple selection -->
<.date_picker
  name="holidays[]"
  label="Company Holidays"
  multiple
  description="Select all company holidays for the year"
  help_text="Click dates to toggle selection"
  placeholder="Select multiple dates"
/>

Multiple Selection Use Cases

<!-- Vacation planning -->
<.date_picker
  name="vacation_days[]"
  label="Vacation Days"
  multiple
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 365)}
  close="manual"
  description="Select all your vacation days"
  help_text="You can select multiple non-consecutive dates"
  placeholder="Choose vacation days"
/>

<!-- Recurring meeting dates -->
<.date_picker
  name="meeting_dates[]"
  label="Meeting Dates"
  multiple
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 90)}
  navigation="extended"
  close="manual"
  description="Select all meeting dates for the quarter"
  help_text="Meetings will be scheduled on these dates"
  placeholder="Select meeting dates"
/>

<!-- Availability calendar -->
<.date_picker
  name="available_dates[]"
  label="Available Dates"
  multiple
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 30)}
  description="Mark your available dates"
  help_text="Others can book appointments on these dates"
  placeholder="Mark availability"
/>

Multiple Selection Behavior

When multiple selection is enabled:

• Calendar remains open after each selection for continued picking
• Selected dates are visually highlighted
• Clicking selected dates deselects them
• Toggle button shows "X dates selected" for multiple selections
• Time picker integration is not supported
• Auto-close mode is automatically disabled

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

# When no dates are selected (hidden input provides empty value)
%{"holidays" => [""]}  # Instead of field being omitted

Date and Time Formatting

Customize how dates are displayed using the display_format attribute with strftime patterns:

Common Date Formats

<!-- ISO format -->
<.date_picker
  name="iso_date"
  label="ISO Date"
  display_format="%Y-%m-%d"  <!-- 2024-01-01 -->
/>

<!-- US format -->
<.date_picker
  name="us_date"
  label="US Date"
  display_format="%m/%d/%Y"  <!-- 01/01/2024 -->
/>

<!-- European format -->
<.date_picker
  name="eu_date"
  label="European Date"
  display_format="%d/%m/%Y"  <!-- 01/01/2024 -->
/>

<!-- Full month name -->
<.date_picker
  name="full_date"
  label="Full Date"
  display_format="%B %-d, %Y"  <!-- January 1, 2024 -->
/>

DateTime Formatting

For date_time_picker, include time patterns in your format:

<!-- 12-hour format with full context -->
<.date_time_picker
  name="appointment"
  label="Appointment"
  time_format="12"
  display_format="%B %-d, %Y at %I:%M %p"  <!-- January 1, 2024 at 02:30 PM -->
/>

<!-- 24-hour format, compact -->
<.date_time_picker
  name="meeting"
  label="Meeting"
  time_format="24"
  display_format="%Y-%m-%d %H:%M"  <!-- 2024-01-01 14:30 -->
/>

<!-- Casual format -->
<.date_time_picker
  name="event"
  label="Event"
  time_format="12"
  display_format="%a, %b %-d at %I:%M %p"  <!-- Mon, Jan 1 at 02:30 PM -->
/>

Week Start Configuration

Customize which day appears in the first column using the week_start attribute to accommodate different cultural preferences:

<!-- Monday start (common in Europe) -->
<.date_picker
  name="european_date"
  label="Date"
  week_start={1}
/>

<!-- Friday start (common in Islamic countries) -->
<.date_picker
  name="islamic_date"
  label="Date"
  week_start={5}
/>

The calendar grid, keyboard navigation, and week-based interactions all adapt to the configured week start.

Date Time Picker

The date_time_picker function combines date selection with precise time input, supporting both 12-hour and 24-hour formats:

<!-- 12-hour format with AM/PM -->
<.date_time_picker
  name="appointment"
  label="Appointment Time"
  time_format="12"
  display_format="%B %-d, %Y at %I:%M %p"
/>

<!-- 24-hour format -->
<.date_time_picker
  name="meeting_start"
  label="Meeting Start"
  time_format="24"
  display_format="%d/%m/%Y %H:%M"
/>

Time Input Features

The time interface provides:

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

Data Type Requirements

Date time pickers require NaiveDateTime or DateTime field types:

# In your schema
schema "appointments" do
  field :scheduled_at, :naive_datetime  # Required for date_time_picker
  # field :date_only, :date             # Use with date_picker instead
end

Date Range Picker

The date_range_picker function provides range selection with visual feedback and interaction patterns:

<!-- Form integration -->
<.form :let={f} for={@changeset}>
  <.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>

<!-- Standalone usage -->
<.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"
/>

Range Selection Patterns

The component supports these interaction patterns:

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

Form Integration Example

# Schema with separate start/end fields
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

Closing Strategies

Control when the calendar closes using the close attribute:

Auto Mode (Default)

Closes immediately after selection:

<.date_picker name="simple" close="auto" label="Simple Date" />

Manual Mode

Keeps calendar open for comparison and multiple adjustments:

<.date_picker name="manual" close="manual" label="Manual Close" />

Confirm Mode

Requires explicit confirmation:

<.date_picker name="confirm" close="confirm" label="Confirmed Date" />

Navigation Modes

Choose from three navigation interfaces based on your use case:

Default Mode

Simple month-to-month navigation with arrow buttons:

<.date_picker name="default_nav" navigation="default" />

Extended Mode

Adds year navigation arrows for faster long-distance navigation:

<.date_picker name="extended_nav" navigation="extended" />

Select Mode

Combines arrows with dropdown menus for direct month/year access:

<.date_picker name="select_nav" navigation="select" />

Form Integration

The date picker supports Phoenix form fields and standalone usage.

Phoenix Forms

Use the field attribute for form integration:

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

Benefits of form integration:

• Automatic value handling from form data
• Built-in error handling and validation messages
• Proper form submission with correct field names
• Seamless changeset integration
• Automatic ID generation for accessibility
• Type conversion between form data and Elixir date types

Complete Form Example

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

  schema "bookings" do
    field :appointment_date, :date
    field :meeting_datetime, :naive_datetime
    field :blocked_dates, {:array, :date}
    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

  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

  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

Standalone Usage

For simpler cases or non-Phoenix forms:

<!-- 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"
/>

Keyboard Navigation

The component provides comprehensive keyboard support for accessibility:

Toggle Button Navigation

Calendar Navigation

Time Picker Navigation (when enabled)

The component implements focus trapping when open, ensuring keyboard navigation stays within the calendar interface.

Implementation Examples

Complete implementations for common scenarios:

Appointment Booking System

<.date_picker
  name="appointment_date"
  label="Appointment Date"
  description="Select your preferred appointment date"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 60)}
  navigation="select"
  help_text="Appointments available Monday-Friday, 9 AM to 5 PM"
  placeholder="Choose your appointment date"
>
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
            <.button variant="solid" color="primary" size="md">Book Appointment</.button>
  </:outer_suffix>
</.date_picker>

Hotel Reservation System

<.date_range_picker
  start_name="check_in"
  end_name="check_out"
  label="Hotel Reservation"
  description="Select your check-in and check-out dates"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 365)}
  display_format="%a, %b %-d"
  help_text="Minimum stay: 1 night, Maximum stay: 30 nights"
  placeholder="Select your stay dates"
>
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
            <.button size="md" variant="solid" color="primary">Check Availability</.button>
  </:outer_suffix>
</.date_range_picker>

Meeting Scheduler

<.date_time_picker
  name="meeting_schedule"
  label="Meeting Schedule"
  description="Schedule your meeting"
  time_format="12"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 30)}
  display_format="%B %-d, %Y at %I:%M %p"
  help_text="Meeting rooms available 8 AM to 6 PM"
  placeholder="Choose meeting time"
>
  <:inner_prefix>
    <.icon name="hero-clock" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
            <.button variant="solid" color="primary" size="md">
      <.icon name="hero-plus" class="size-4" /> Schedule Meeting
    </.button>
  </:outer_suffix>
</.date_time_picker>

Project Management Dashboard

<.date_picker
  name="project_milestones[]"
  label="Project Milestones"
  multiple
  description="Select key project milestone dates"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 180)}
  close="manual"
  help_text="You can select multiple dates for different milestones"
  placeholder="Choose milestone dates"
>
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
  <:inner_suffix>
    <.icon name="hero-queue-list" class="icon" />
  </:inner_suffix>
  <:outer_suffix>
            <.button size="md" variant="soft" color="primary">Add to Schedule</.button>
  </:outer_suffix>
</.date_picker>

Event Planning Interface

<.date_time_picker
  name="event_scheduler"
  label="Event Start Time"
  description="When does your event start?"
  time_format="12"
  min={Date.utc_today()}
  navigation="extended"
  close="confirm"
  display_format="%a, %B %-d at %I:%M %p"
  placeholder="Schedule your event"
>
  <:outer_prefix class="px-3">Event:</:outer_prefix>
  <:inner_prefix>
    <.icon name="hero-clock" class="icon" />
  </:inner_prefix>
  <:inner_suffix>
    <.icon name="hero-bell" class="icon" />
  </:inner_suffix>
  <:outer_suffix>
            <.button size="md" variant="solid" color="primary">Create Event</.button>
  </:outer_suffix>
</.date_time_picker>

User Profile - Birth Date

<.date_picker
  name="birthday_picker"
  label="Date of Birth"
  description="Select your birth date"
  min={~D[1900-01-01]}
  max={Date.utc_today()}
  navigation="select"
  display_format="%B %-d, %Y"
  week_start={1}
  placeholder="Enter your birth date"
>
  <:inner_prefix>
    <.icon name="hero-cake" class="icon" />
  </:inner_prefix>
</.date_picker>