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

Custom Disabled Dates

Beyond min and max constraints, the disabled_dates attribute provides flexible date disabling through specific dates, ranges, and pattern matching. All patterns are evaluated together using union logic - a date is disabled if it matches ANY of the provided criteria.

Exact Date Matching

Specific dates (~D[YYYY-MM-DD]) disable individual dates. This is useful for blocking known unavailable dates like holidays or specific blocked days. Multiple dates can be provided in the list.

Date ranges (Date.range/2) disable all dates within a continuous range, inclusive of start and end dates. Ranges are automatically expanded server-side, making them efficient for blocking vacation periods or extended closures.

Pattern-Based Disabling

Shortcut patterns provide quick access to common scenarios:

• :weekends - Disables all Saturdays and Sundays
• :weekdays - Disables Monday through Friday (inverse of weekends)

Day of month patterns ({:day, N}) disable a specific day number across all months and years. For example, {:day, 15} disables the 15th of every month. When a month doesn't have the specified day (like day 31 in February), the pattern has no effect for that month.

Weekday patterns ({:weekday, N}) disable specific days of the week using ISO-8601 standard numbering (1=Monday, 7=Sunday). For example, {:weekday, 3} disables all Wednesdays. Multiple weekday patterns can be combined to create custom weekly availability schedules.

ISO week patterns ({:week, N}) disable all dates within a specific ISO week number (1-53). ISO weeks always start on Monday and are calculated according to ISO-8601 standard.

Month-day patterns ({:month_day, M, D}) disable recurring annual dates, such as holidays that fall on the same calendar date each year. For example, {:month_day, 12, 25} disables December 25th across all years.

Month patterns ({:month, M}) disable entire months across all years. Month numbers are 1-based (1=January, 12=December).

Year patterns ({:year, YYYY}) disable all dates within a specific year.

Examples

<!-- Business days only: disable all weekends -->
<.date_picker
  name="business_date"
  label="Appointment Date"
  disabled_dates={[:weekends]}
/>

<!-- Block specific dates and ranges together -->
<.date_picker
  name="booking"
  label="Booking Date"
  disabled_dates={[
    ~D[2025-12-25],
    ~D[2025-01-01],
    Date.range(~D[2026-01-02], ~D[2026-01-15])
  ]}
/>

<!-- Complex pattern combination -->
<.date_picker
  name="availability"
  label="Available Date"
  disabled_dates={[
    :weekends,              # No weekends
    {:weekday, 3},          # No Wednesdays
    {:day, 15},             # No 15th of any month
    {:month_day, 12, 25},   # No Christmas
    {:month, 4},            # No April dates
    {:week, 33}             # No ISO week 33
  ]}
/>

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

Selection Granularity

Control the level of date precision using the granularity attribute. This determines whether users select specific days, entire months, or entire years:

Day Granularity (Default)

Standard date selection for specific days:

<.date_picker
  name="appointment"
  label="Appointment Date"
  granularity="day"
  placeholder="Select a specific day"
/>

Month Granularity

Select entire months, with dates normalized to the first day of the selected month. The calendar displays a grid of months instead of days:

<.date_picker
  name="billing_period"
  label="Billing Period"
  granularity="month"
  placeholder="Select a month"
/>

Year Granularity

Select entire years, with dates normalized to January 1st of the selected year. The calendar displays a grid of years:

<.date_picker
  name="graduation_year"
  label="Graduation Year"
  granularity="year"
  placeholder="Select a year"
/>

Practical Use Cases

<!-- Financial reporting - month selection -->
<.date_picker
  name="report_month"
  label="Report Period"
  granularity="month"
  min={~D[2020-01-01]}
  max={Date.utc_today()}
  description="Select the month for financial reporting"
  placeholder="Choose reporting month"
/>

<!-- Academic year selection -->
<.date_picker
  name="academic_year"
  label="Academic Year"
  granularity="year"
  min={~D[2000-01-01]}
  max={Date.add(Date.utc_today(), 365)}
  description="Select your graduation year"
  placeholder="Select year"
/>

<!-- Contract period - month range -->
<.date_range_picker
  start_name="contract_start"
  end_name="contract_end"
  label="Contract Period"
  granularity="month"
  description="Select contract duration by month"
  placeholder="Select month range"
/>

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

Granularity Behavior

When using different granularity levels:

• Date Normalization: Selected dates are automatically normalized to the start of the period (first of month for "month", January 1st for "year")
• Display Format: Format automatically adjusts unless explicitly overridden with display_format
• Time Picker: Automatically disabled for "month" and "year" modes (only available with "day")
• Range Selection: Works with all granularity levels, applying normalization to both start and end dates
• Constraints: min and max constraints apply at the selected granularity level

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

Navigation behavior adapts based on the selected granularity:

Day Granularity: | Key | Action | |-----|--------| | ↑/↓ | Move to same day in previous/next week (7 days) | | ←/→ | Move to previous/next day | | Home/End | Move to first/last day of current week | | PageUp/PageDown | Move to same day in previous/next month | | Enter/Space | Select focused date | | Escape | Close calendar |

Month Granularity: | Key | Action | |-----|--------| | ↑/↓ | Move up/down by 3 months (grid row) | | ←/→ | Move to previous/next month | | Enter/Space | Select focused month | | Escape | Close calendar |

Year Granularity: | Key | Action | |-----|--------| | ↑/↓ | Move up/down by 3 years (grid row) | | ←/→ | Move to previous/next year | | Enter/Space | Select focused year | | Escape | Close calendar |

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>

Financial Reporting - Month Selection

<.date_picker
  name="reporting_month"
  label="Reporting Period"
  description="Select the month for financial reporting"
  granularity="month"
  min={~D[2020-01-01]}
  max={Date.utc_today()}
  help_text="Reports are generated monthly"
  placeholder="Choose reporting month"
>
  <:inner_prefix>
    <.icon name="hero-chart-bar" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
    <.button size="md" variant="solid" color="primary">Generate Report</.button>
  </:outer_suffix>
</.date_picker>

Academic Records - Year Selection

<.date_picker
  name="graduation_year"
  label="Graduation Year"
  description="Select your graduation year"
  granularity="year"
  min={~D[1950-01-01]}
  max={Date.add(Date.utc_today(), 3650)}
  navigation="default"
  placeholder="Select year"
>
  <:inner_prefix>
    <.icon name="hero-academic-cap" class="icon" />
  </:inner_prefix>
</.date_picker>

Subscription Period - Month Range

<.date_range_picker
  start_name="subscription_start"
  end_name="subscription_end"
  label="Subscription Period"
  description="Select your subscription period"
  granularity="month"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 730)}
  help_text="Subscriptions are billed monthly"
  placeholder="Choose subscription period"
>
  <:inner_prefix>
    <.icon name="hero-calendar" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
    <.button size="md" variant="solid" color="primary">Calculate Price</.button>
  </:outer_suffix>
</.date_range_picker>