Fluxon.Components.DatePicker (Fluxon v2.4.0-rc.2)

Provides <.date_picker>, <.date_time_picker>, and <.date_range_picker> components for calendar-based date selection in a dropdown.

This module renders a compact input that opens a floating calendar dropdown on click. It supports single date, multiple date, and date range selection, with optional time picking, three granularity modes (day, month, year), three navigation styles, min/max constraints, flexible disabled date patterns, an typeable text input mode, locale support for 30 languages, and full keyboard navigation with accessibility built in.

Calendar vs DatePicker

Both components share the same calendar grid, but serve different layout needs:

Feature	Calendar	DatePicker
Display	Always inline	Dropdown on click
Toggle	None	Button or typeable input
Time picker	Not supported	Supported
Display format	Not applicable	Configurable

Use Calendar when the calendar should always be visible. Use DatePicker when you need a compact input that opens a calendar dropdown.

Basic Usage

Render a date picker for single date selection:

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

For date-and-time or date range selection, use the dedicated components:

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

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

Selection Modes

Single Selection

The default mode selects one date at a time. Clicking a new date replaces the previous selection. Clicking the selected date deselects it (unless allow_deselect is false):

<.date_picker name="date" label="Pick a date" />
<.date_picker name="date" label="Required date" allow_deselect={false} />

Multiple Selection

Enable with the multiple attribute. Each click toggles the date on or off. The calendar stays open after each selection. The toggle displays "X dates selected":

<.date_picker name="holidays[]" label="Company Holidays" multiple />

Empty Values in Multiple Select

A hidden input with an empty value is included so the field is always present in form submissions. When no dates are selected, the form data contains [""]. Filter out empty strings when processing:

selected = Enum.reject(params["holidays"] || [], &(&1 == ""))

Range Selection

Use <.date_range_picker> for start/end date pairs. The first click sets the start date, the second click sets the end date. Dates between the two are visually highlighted. Clicking a selected endpoint clears and restarts selection:

<.date_range_picker
  start_name="check_in"
  end_name="check_out"
  label="Booking Period"
/>

Editable Input

Replace the toggle button with an typeable text input using the typeable attribute. Users type dates directly using the configured format with automatic separator insertion:

<.date_picker name="date" label="Date" typeable />

Control the input format with input_format. Any format containing dd, mm, and yyyy separated by a consistent single-character separator is supported:

<.date_picker name="date" typeable input_format="mm/dd/yyyy" />
<.date_picker name="date" typeable input_format="dd.mm.yyyy" />
<.date_picker name="date" typeable input_format="yyyy-mm-dd" />

When input_format is not specified, the format is determined by the locale:

<.date_picker name="date" typeable locale="de" />
<.date_picker name="date" typeable locale="sv" />

Editable Mode Constraints

Editable mode requires single date selection with day granularity. It is not supported with multiple, range, or granularity="month" / "year". Using typeable with unsupported modes emits a warning and disables the feature.

Selection Granularity

Control the precision level with the granularity attribute. The calendar grid adapts its layout accordingly:

<.date_picker name="date" granularity="day" />
<.date_picker name="month" granularity="month" />
<.date_picker name="year" granularity="year" />

Granularity	Grid	Navigation Step	Value Format
`day`	7-column, 6 weeks	Month	`2025-01-15`
`month`	3-column, 12 months	Year	`2025-03`
`year`	3-column, 12 years	Decade	`2025`

Selected dates are normalized to the start of the period: first of month for "month", January 1st for "year". All selection modes (single, multiple, range) work with every granularity.

Time Picker and Granularity

The time picker is only available with granularity="day". Month and year modes automatically disable the time picker regardless of other attributes.

Navigation

Three navigation styles control the calendar header UI:

<.date_picker name="date" navigation="default" />
<.date_picker name="date" navigation="extended" />
<.date_picker name="date" navigation="select" />

Style	Controls
`default`	Previous/next month buttons with month-year title
`extended`	Adds previous/next year buttons
`select`	Month and year dropdown selects with next/previous buttons

Navigation buttons are automatically disabled when they would move past min or max boundaries. In select mode, dropdown options are limited to valid ranges.

Date Constraints

Min and Max

Restrict the selectable date range. Dates outside the range are disabled and cannot be selected via click or keyboard:

<.date_picker name="date" min={Date.utc_today()} />
<.date_picker name="date" min={~D[2025-01-01]} max={~D[2025-12-31]} />

Disabled Dates

The disabled_dates attribute accepts a list of patterns to disable specific dates. Multiple patterns can be combined (union logic -- a date is disabled if it matches any pattern):

<.date_picker name="date" disabled_dates={[:weekends]} />
<.date_picker name="date" disabled_dates={[~D[2025-12-25], {:month_day, 1, 1}]} />

Available patterns:

Pattern	Example	Description
`Date`	`~D[2025-01-15]`	Specific date
`Date.Range`	`Date.range(~D[2025-01-01], ~D[2025-01-10])`	Date range
`:weekends`	`:weekends`	Saturdays and Sundays
`:weekdays`	`:weekdays`	Monday through Friday
`{:day, d}`	`{:day, 15}`	Day of month (every month)
`{:weekday, n}`	`{:weekday, 3}`	Day of week (1=Mon, 7=Sun)
`{:week, n}`	`{:week, 33}`	ISO week number
`{:month_day, m, d}`	`{:month_day, 12, 25}`	Recurring annual date
`{:month, m}`	`{:month, 4}`	Entire month
`{:year, y}`	`{:year, 2025}`	Entire year

Keyboard navigation automatically skips disabled dates.

Client-Side Only

Date constraints provide client-side validation only. Always implement corresponding server-side validation using Ecto changesets.

Date Time Picker

The <.date_time_picker> combines calendar date selection with time input fields supporting both 12-hour and 24-hour formats:

<.date_time_picker name="appointment" label="Time" time_format="12" />
<.date_time_picker name="meeting" label="Meeting" time_format="24" />

The time interface provides hour, minute, and second inputs with direct keyboard entry, arrow key increment/decrement, and AM/PM toggle via a/p keys in 12-hour mode. Time inputs are disabled until a date is selected.

Date time pickers require NaiveDateTime or DateTime field types in your schema:

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

Timezone Handling

The component treats all dates and times as UTC. Handle timezone conversion in your application logic.

Display Format

Customize how dates appear in the toggle using display_format with strftime patterns:

<.date_picker name="date" display_format="%Y-%m-%d" />
<.date_picker name="date" display_format="%B %-d, %Y" />
<.date_time_picker name="dt" display_format="%B %-d, %Y at %I:%M %p" />

The format automatically adjusts for month and year granularity unless explicitly overridden. Time format specifiers (%H, %I, %M, %p) should only be used with date_time_picker.

Closing Behavior

Control when the calendar dropdown closes with the close attribute:

Mode	Behavior
`auto`	Closes immediately after selection (default)
`manual`	Stays open after selection
`confirm`	Shows Cancel/Apply buttons, requires explicit confirmation

<.date_picker name="date" close="auto" />
<.date_picker name="date" close="manual" />
<.date_picker name="date" close="confirm" />

Auto Mode Fallback

The component automatically uses manual close behavior when features require multiple interactions (time picker, range selection, multiple selection).

Presets

Display a sidebar of preset date shortcuts next to the calendar grid using the presets attribute. Each preset is a tuple with a label and one or two dates:

<.date_picker
  name="date"
  presets={[
    {"Today", Date.utc_today()},
    {"Tomorrow", Date.add(Date.utc_today(), 1)},
    {"A week from now", Date.add(Date.utc_today(), 7)},
    {"A month from now", Date.shift(Date.utc_today(), month: 1)}
  ]}
/>

For range pickers, pass three-element tuples with start and end dates:

<.date_range_picker
  start_name="start"
  end_name="end"
  presets={[
    {"This week", ~D[2026-02-23], ~D[2026-02-28]},
    {"Next week", ~D[2026-03-02], ~D[2026-03-08]}
  ]}
/>

Clicking a preset selects the date(s) and navigates the calendar. The active preset is highlighted when the current selection matches. In confirm mode, preset selections are pending until Apply is clicked.

Size Variants

Scale the toggle for different contexts:

<.date_picker name="date" size="xs" />
<.date_picker name="date" size="sm" />
<.date_picker name="date" size="md" />
<.date_picker name="date" size="lg" />
<.date_picker name="date" size="xl" />

Size	Height	Use Case
`xs`	28px	Compact UI, dashboard widgets
`sm`	32px	Secondary inputs, sidebar forms
`md`	36px	Default size
`lg`	40px	Primary selections
`xl`	44px	Hero sections, prominent forms

Affixes

Inner Affixes

Add content inside the toggle border. Icons are automatically sized to match:

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

Outer Affixes

Place content outside the toggle border for buttons, labels, or interactive elements:

<.date_picker name="date" label="Due Date" placeholder="Select date">
  <:outer_prefix class="px-3 text-foreground-soft">Due:</:outer_prefix>
  <:outer_suffix>
    <.button size="md">Apply</.button>
  </:outer_suffix>
</.date_picker>

Size Matching with Affixes

Match the size of buttons or components in affix slots with the date picker's size:

<.date_picker name="date" size="lg">
  <:outer_suffix>
    <.button size="lg">Action</.button>
  </:outer_suffix>
</.date_picker>

Form Integration

Use the field attribute to bind to a Phoenix form field for automatic value tracking, error handling, and form submission:

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

Range selection with form fields:

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

For standalone usage without a form, use name and value directly:

<.date_picker name="date" value={~D[2025-06-15]} />
<.date_range_picker start_name="from" end_name="to" start_value={@from} end_value={@to} />

Type Handling

The component accepts Date, NaiveDateTime, DateTime structs, and ISO 8601 strings. Multiple selection accepts lists of these types. Form values are submitted as ISO 8601 strings.

Week Start

Customize which day appears in the first column:

<.date_picker name="date" week_start={1} />

Value	Weekday	Common Usage
0	Sunday	Default (US, Canada)
1	Monday	Europe, ISO 8601
5	Friday	Islamic countries
6	Saturday	Nepal

Locale

The locale attribute localizes weekday abbreviations, month names, navigation labels, time picker labels, and confirmation button text. Unsupported locales fall back to English:

<.date_picker name="fecha" label="Fecha" locale="es" />
<.date_time_picker name="rdv" label="Rendez-vous" locale="fr" time_format="24" />
<.date_picker name="datum" label="Datum" locale="de" navigation="select" />

Supported locales: ar, bg, cs, da, de, el, en, es, fi, fr, hr, hu, it, ja, ko, nb, nl, pl, pt, pt-BR, ro, ru, sk, sr, sv, th, tr, uk, vi, zh.

Translating Labels and Placeholders

The locale attribute translates the component's own text (month names, weekday abbreviations, button labels). Attributes like placeholder, label, and help_text should be translated by your application (e.g., via Gettext).

Keyboard Navigation

Toggle

Key	Action
`Space` / `Enter`	Open or close the calendar
`Tab` / `Shift+Tab`	Move focus to/from the date picker

Calendar Grid

Key	Day Mode	Month Mode	Year Mode
`Arrow Left`	Previous day	Previous month	Previous year
`Arrow Right`	Next day	Next month	Next year
`Arrow Up`	Previous week (7 days)	Up 3 months	Up 3 years
`Arrow Down`	Next week (7 days)	Down 3 months	Down 3 years
`Home` / `End`	First/last day of week	--	--
`Page Up` / `Page Down`	Previous/next month	--	--
`Enter` / `Space`	Select focused date	Select focused month	Select focused year
`Escape`	Close calendar	Close calendar	Close calendar

When a focused date is disabled, the keyboard continues in the same direction until it finds an enabled date.

Time Picker (when enabled)

Key	Action
`Arrow Up` / `Arrow Down`	Increment/decrement value
`0`-`9`	Direct value input
`a` / `p`	Switch AM/PM (12-hour format)
`Tab`	Move between hour, minute, second, AM/PM fields

Accessibility

The calendar dropdown uses role="dialog" with aria-modal="true" and an aria-label. The toggle button has role="button", aria-haspopup="true", and aria-expanded reflecting open/close state. Date cells use aria-selected for current selection and aria-disabled for constrained dates. Weekday headers use role="columnheader". Time inputs carry aria-label, aria-valuenow, aria-valuemin, and aria-valuemax attributes. Focus is trapped within the calendar while open and returned to the toggle on close. The typeable input receives the label's for association and aria-invalid when errors are present.

Common Patterns

Business Day Appointment

<.date_picker
  name="appointment"
  label="Appointment Date"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 60)}
  disabled_dates={[:weekends]}
  navigation="select"
  placeholder="Choose your appointment date"
>
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
</.date_picker>

Hotel Booking Range

<.date_range_picker
  start_name="check_in"
  end_name="check_out"
  label="Stay Period"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 365)}
  display_format="%a, %b %-d"
  placeholder="Select your stay dates"
/>

Meeting Scheduler with Time

<.date_time_picker
  name="meeting"
  label="Meeting"
  time_format="12"
  min={Date.utc_today()}
  display_format="%B %-d, %Y at %I:%M %p"
  placeholder="Choose meeting time"
/>

Birth Date with Select Navigation

<.date_picker
  name="birth_date"
  label="Date of Birth"
  min={~D[1900-01-01]}
  max={Date.utc_today()}
  navigation="select"
  display_format="%B %-d, %Y"
  placeholder="Select birth date"
/>

Month/Year Pickers

<.date_picker name="report_month" label="Report Period" granularity="month" />
<.date_picker name="grad_year" label="Graduation Year" granularity="year" />

Multiple Date Selection

<.date_picker
  name="holidays[]"
  label="Company Holidays"
  multiple
  close="manual"
  min={~D[2025-01-01]}
  max={~D[2025-12-31]}
  placeholder="Select holiday dates"
/>

Summary

Components

date_picker(assigns)

Renders a date picker for single or multiple date selection.

date_range_picker(assigns)

Renders a date range picker for selecting start and end dates.

date_time_picker(assigns)

Renders a date time picker with calendar-based date selection and time input.

Components

date_picker(assigns)

Renders a date picker for single or multiple date selection.

Opens a floating calendar dropdown from a toggle button (or typeable text input when typeable is set). Supports single and multiple selection modes, three granularity levels, and configurable closing behavior.

<.date_picker
  field={f[:appointment_date]}
  label="Appointment Date"
  min={Date.utc_today()}
  placeholder="Select a date"
/>

Attributes

field (Phoenix.HTML.FormField) - The form field to bind to. When provided, the component automatically handles value tracking, errors, and form submission.
name (:any) - The form name for the date picker. Required when not using the field attribute. For multiple selections, this will be automatically suffixed with [].
value (:any) - The current selected value(s). For multiple selections, this should be a list. When using forms, this is automatically handled by the field attribute.
typeable (:boolean) - When true, replaces the toggle button with an typeable text input, allowing users to manually type the date. Users type the full date using the configured input_format separator (e.g., "01/15/2025"). Invalid dates are silently ignored.
Defaults to false.
input_format (:string) - The format for the typeable text input when typeable: true. Accepts any format string containing dd, mm, and yyyy separated by a consistent single-character separator (e.g., /, ., -).
Examples: "mm/dd/yyyy", "dd/mm/yyyy", "dd.mm.yyyy", "yyyy-mm-dd", "yyyy/mm/dd"
When not specified, the format is determined by the locale attribute. For example, locale="de" defaults to "dd.mm.yyyy" and locale="sv" defaults to "yyyy-mm-dd".
Defaults to nil.
id (:any) - The unique identifier for the date picker component. When not provided, a random ID will be generated. Defaults to nil.
autofocus (:boolean) - Whether the input should have the autofocus attribute. Defaults to false.
min (Date) - The earliest date that can be selected. Dates before this will be disabled. Defaults to nil.
max (Date) - The latest date that can be selected. Dates after this will be disabled. Defaults to nil.
week_start (:integer) - The day of the week that should appear in the first column.
- 0: Sunday (default)
- 1: Monday
- 2: Tuesday
- 3: Wednesday
- 4: Thursday
- 5: Friday
- 6: Saturday
Defaults to 0.
size (:string) - Controls the size of the date picker component:
- "xs": Extra small size, suitable for compact UIs
- "sm": Small size, suitable for compact UIs
- "md": Default size, suitable for most use cases
- "lg": Large size, suitable for prominent selections
- "xl": Extra large size, suitable for hero sections
Defaults to "md".
class (:any) - Additional CSS classes to be applied to the date picker calendar container. These classes will be merged with the default styles.
Defaults to nil.
granularity (:string) - Controls the selection granularity:
- "day": Select specific days (default)
- "month": Select entire months (dates normalized to first of month)
- "year": Select entire years (dates normalized to first of year)
Defaults to "day".
close (:string) - Controls how the date picker closes after selection:
- "auto": Closes immediately after selection (default)
- "manual": Stays open after selection
- "confirm": Requires explicit confirmation via button
Defaults to "auto".
navigation (:string) - Controls the calendar navigation interface:
- "default": Month arrows only
- "extended": Month and year arrows
- "select": Month arrows + year/month dropdowns
Defaults to "default".
disabled (:boolean) - When true, disables the date picker component. Disabled date pickers cannot be interacted with and appear visually muted.
Defaults to false.
label (:string) - The primary label for the date picker. This text is displayed above the date picker and is used for accessibility purposes.
Defaults to nil.
sublabel (:string) - Additional context displayed to the side of the main label. Useful for providing extra information without cluttering the main label.
Defaults to nil.
description (:string) - A longer description to provide more context about the date picker. This appears below the label but above the date picker element.
Defaults to nil.
help_text (:string) - Help text to display below the date picker. This can provide additional context or instructions for using the date picker.
Defaults to nil.
placeholder (:string) - Text to display when no date is selected. This text appears in the date picker toggle and helps guide users to make a selection.
Defaults to nil.
errors (:list) - List of error messages to display below the date picker. These are automatically handled when using the field attribute with form validation.
Defaults to [].
disabled_dates (:list) - List of dates, date ranges, or patterns to disable. Accepts:
- Specific dates: ~D[2025-01-15]
- Date ranges: Date.range(~D[2025-01-01], ~D[2025-01-10])
- Day shortcuts: :weekends, :weekdays
- Day of month: {:day, 15} (disables 15th of every month)
- Weekday: {:weekday, 3} (disables all Wednesdays; 1=Monday, 7=Sunday)
- ISO week: {:week, 33} (disables entire ISO week 33)
- Recurring annual dates: {:month_day, 12, 25} (disables December 25th every year)
- Month pattern: {:month, 4} (disables all April dates)
- Year pattern: {:year, 2025} (disables all 2025 dates)
All strategies work together (union) - a date is disabled if it matches ANY of the criteria.
Defaults to [].
allow_deselect (:boolean) - When false, prevents deselecting the current selection by clicking on it. In single mode, the selected date cannot be unselected. In multiple mode, at least one date must remain selected. In range mode, clicking the start date won't clear the range.
Defaults to true.
locale (:string) - Locale for date formatting (e.g., 'en', 'es', 'fr', 'de', 'pt-BR'). Localizes weekday abbreviations, month names, navigation labels, time picker labels, and confirmation buttons. Unsupported locales fall back to English. Defaults to "en".
presets (:list) - List of preset date shortcuts displayed as a sidebar next to the calendar.
Each preset is a tuple with the label as the first element:
- Single date: {"Today", ~D[2026-02-28]} or {"Today", Date.utc_today()}
- Date range: {"This week", ~D[2026-02-24], ~D[2026-02-28]}
Defaults to [].
multiple (:boolean) - When true, allows selecting multiple dates. This submits an array of dates and keeps the calendar open after each selection to facilitate choosing multiple dates.
Defaults to false.
display_format (:string) - The format string used to display the selected date(s) in the toggle button. Uses strftime format. Common 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)
Defaults to "%b %-d, %Y".

Slots

inner_prefix - Content placed inside the date picker field's border, before the date display. Ideal for icons or short textual prefixes. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the inner prefix container.
outer_prefix - Content placed outside and before the date picker field. Useful for buttons, dropdowns, or other interactive elements associated with the date picker's start. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the outer prefix container.
inner_suffix - Content placed inside the date picker field's border, after the date display. Suitable for icons, clear buttons, or loading indicators. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the inner suffix container.
outer_suffix - Content placed outside and after the date picker field. Useful for action buttons or other controls related to the date picker's end. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the outer suffix container.

date_range_picker(assigns)

Renders a date range picker for selecting start and end dates.

Provides a calendar interface for range selection with visual highlighting between endpoints. Uses start_field/end_field for form integration or start_name/end_name with start_value/end_value for standalone usage.

<.date_range_picker
  start_name="check_in"
  end_name="check_out"
  label="Stay Period"
  min={Date.utc_today()}
  placeholder="Select your dates"
/>

Attributes

start_field (Phoenix.HTML.FormField) - The form field for the start date when using range selection with forms. Required when range={true} and using form integration.
end_field (Phoenix.HTML.FormField) - The form field for the end date when using range selection with forms. Required when range={true} and using form integration.
start_name (:any) - The form name for the start date when using range selection without forms. Required when range={true} and not using form integration.
end_name (:any) - The form name for the end date when using range selection without forms. Required when range={true} and not using form integration.
start_value (:any) - The current start date value when using range selection without forms.
end_value (:any) - The current end date value when using range selection without forms.
id (:any) - The unique identifier for the date picker component. When not provided, a random ID will be generated. Defaults to nil.
autofocus (:boolean) - Whether the input should have the autofocus attribute. Defaults to false.
min (Date) - The earliest date that can be selected. Dates before this will be disabled. Defaults to nil.
max (Date) - The latest date that can be selected. Dates after this will be disabled. Defaults to nil.
week_start (:integer) - The day of the week that should appear in the first column.
- 0: Sunday (default)
- 1: Monday
- 2: Tuesday
- 3: Wednesday
- 4: Thursday
- 5: Friday
- 6: Saturday
Defaults to 0.
size (:string) - Controls the size of the date picker component:
- "xs": Extra small size, suitable for compact UIs
- "sm": Small size, suitable for compact UIs
- "md": Default size, suitable for most use cases
- "lg": Large size, suitable for prominent selections
- "xl": Extra large size, suitable for hero sections
Defaults to "md".
class (:any) - Additional CSS classes to be applied to the date picker calendar container. These classes will be merged with the default styles.
Defaults to nil.
granularity (:string) - Controls the selection granularity:
- "day": Select specific days (default)
- "month": Select entire months (dates normalized to first of month)
- "year": Select entire years (dates normalized to first of year)
Defaults to "day".
close (:string) - Controls how the date picker closes after selection:
- "auto": Closes immediately after selection (default)
- "manual": Stays open after selection
- "confirm": Requires explicit confirmation via button
Defaults to "auto".
navigation (:string) - Controls the calendar navigation interface:
- "default": Month arrows only
- "extended": Month and year arrows
- "select": Month arrows + year/month dropdowns
Defaults to "default".
disabled (:boolean) - When true, disables the date picker component. Disabled date pickers cannot be interacted with and appear visually muted.
Defaults to false.
label (:string) - The primary label for the date picker. This text is displayed above the date picker and is used for accessibility purposes.
Defaults to nil.
sublabel (:string) - Additional context displayed to the side of the main label. Useful for providing extra information without cluttering the main label.
Defaults to nil.
description (:string) - A longer description to provide more context about the date picker. This appears below the label but above the date picker element.
Defaults to nil.
help_text (:string) - Help text to display below the date picker. This can provide additional context or instructions for using the date picker.
Defaults to nil.
placeholder (:string) - Text to display when no date is selected. This text appears in the date picker toggle and helps guide users to make a selection.
Defaults to nil.
errors (:list) - List of error messages to display below the date picker. These are automatically handled when using the field attribute with form validation.
Defaults to [].
disabled_dates (:list) - List of dates, date ranges, or patterns to disable. Accepts:
- Specific dates: ~D[2025-01-15]
- Date ranges: Date.range(~D[2025-01-01], ~D[2025-01-10])
- Day shortcuts: :weekends, :weekdays
- Day of month: {:day, 15} (disables 15th of every month)
- Weekday: {:weekday, 3} (disables all Wednesdays; 1=Monday, 7=Sunday)
- ISO week: {:week, 33} (disables entire ISO week 33)
- Recurring annual dates: {:month_day, 12, 25} (disables December 25th every year)
- Month pattern: {:month, 4} (disables all April dates)
- Year pattern: {:year, 2025} (disables all 2025 dates)
All strategies work together (union) - a date is disabled if it matches ANY of the criteria.
Defaults to [].
allow_deselect (:boolean) - When false, prevents deselecting the current selection by clicking on it. In single mode, the selected date cannot be unselected. In multiple mode, at least one date must remain selected. In range mode, clicking the start date won't clear the range.
Defaults to true.
locale (:string) - Locale for date formatting (e.g., 'en', 'es', 'fr', 'de', 'pt-BR'). Localizes weekday abbreviations, month names, navigation labels, time picker labels, and confirmation buttons. Unsupported locales fall back to English. Defaults to "en".
presets (:list) - List of preset date shortcuts displayed as a sidebar next to the calendar.
Each preset is a tuple with the label as the first element:
- Single date: {"Today", ~D[2026-02-28]} or {"Today", Date.utc_today()}
- Date range: {"This week", ~D[2026-02-24], ~D[2026-02-28]}
Defaults to [].
display_format (:string) - The format string used to display the selected date(s) in the toggle button. Uses strftime format. Common 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)
Defaults to "%b %-d, %Y".

Slots

inner_prefix - Content placed inside the date picker field's border, before the date display. Ideal for icons or short textual prefixes. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the inner prefix container.
outer_prefix - Content placed outside and before the date picker field. Useful for buttons, dropdowns, or other interactive elements associated with the date picker's start. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the outer prefix container.
inner_suffix - Content placed inside the date picker field's border, after the date display. Suitable for icons, clear buttons, or loading indicators. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the inner suffix container.
outer_suffix - Content placed outside and after the date picker field. Useful for action buttons or other controls related to the date picker's end. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the outer suffix container.

date_time_picker(assigns)

Renders a date time picker with calendar-based date selection and time input.

Combines date_picker with hour, minute, and second inputs supporting 12-hour (with AM/PM) and 24-hour formats. Requires NaiveDateTime or DateTime field types.

<.date_time_picker
  name="meeting"
  label="Meeting"
  time_format="12"
  display_format="%B %-d, %Y at %I:%M %p"
  placeholder="Choose meeting time"
/>

Attributes

field (Phoenix.HTML.FormField) - The form field to bind to. When provided, the component automatically handles value tracking, errors, and form submission.
name (:any) - The form name for the date picker. Required when not using the field attribute. For multiple selections, this will be automatically suffixed with [].
value (:any) - The current selected value(s). For multiple selections, this should be a list. When using forms, this is automatically handled by the field attribute.
typeable (:boolean) - When true, replaces the toggle button with an typeable text input, allowing users to manually type the date. Users type the full date using the configured input_format separator (e.g., "01/15/2025"). Invalid dates are silently ignored.
Defaults to false.
input_format (:string) - The format for the typeable text input when typeable: true. Accepts any format string containing dd, mm, and yyyy separated by a consistent single-character separator (e.g., /, ., -).
Examples: "mm/dd/yyyy", "dd/mm/yyyy", "dd.mm.yyyy", "yyyy-mm-dd", "yyyy/mm/dd"
When not specified, the format is determined by the locale attribute. For example, locale="de" defaults to "dd.mm.yyyy" and locale="sv" defaults to "yyyy-mm-dd".
Defaults to nil.
id (:any) - The unique identifier for the date picker component. When not provided, a random ID will be generated. Defaults to nil.
autofocus (:boolean) - Whether the input should have the autofocus attribute. Defaults to false.
min (Date) - The earliest date that can be selected. Dates before this will be disabled. Defaults to nil.
max (Date) - The latest date that can be selected. Dates after this will be disabled. Defaults to nil.
week_start (:integer) - The day of the week that should appear in the first column.
- 0: Sunday (default)
- 1: Monday
- 2: Tuesday
- 3: Wednesday
- 4: Thursday
- 5: Friday
- 6: Saturday
Defaults to 0.
size (:string) - Controls the size of the date picker component:
- "xs": Extra small size, suitable for compact UIs
- "sm": Small size, suitable for compact UIs
- "md": Default size, suitable for most use cases
- "lg": Large size, suitable for prominent selections
- "xl": Extra large size, suitable for hero sections
Defaults to "md".
class (:any) - Additional CSS classes to be applied to the date picker calendar container. These classes will be merged with the default styles.
Defaults to nil.
granularity (:string) - Controls the selection granularity:
- "day": Select specific days (default)
- "month": Select entire months (dates normalized to first of month)
- "year": Select entire years (dates normalized to first of year)
Defaults to "day".
close (:string) - Controls how the date picker closes after selection:
- "auto": Closes immediately after selection (default)
- "manual": Stays open after selection
- "confirm": Requires explicit confirmation via button
Defaults to "auto".
navigation (:string) - Controls the calendar navigation interface:
- "default": Month arrows only
- "extended": Month and year arrows
- "select": Month arrows + year/month dropdowns
Defaults to "default".
disabled (:boolean) - When true, disables the date picker component. Disabled date pickers cannot be interacted with and appear visually muted.
Defaults to false.
label (:string) - The primary label for the date picker. This text is displayed above the date picker and is used for accessibility purposes.
Defaults to nil.
sublabel (:string) - Additional context displayed to the side of the main label. Useful for providing extra information without cluttering the main label.
Defaults to nil.
description (:string) - A longer description to provide more context about the date picker. This appears below the label but above the date picker element.
Defaults to nil.
help_text (:string) - Help text to display below the date picker. This can provide additional context or instructions for using the date picker.
Defaults to nil.
placeholder (:string) - Text to display when no date is selected. This text appears in the date picker toggle and helps guide users to make a selection.
Defaults to nil.
errors (:list) - List of error messages to display below the date picker. These are automatically handled when using the field attribute with form validation.
Defaults to [].
disabled_dates (:list) - List of dates, date ranges, or patterns to disable. Accepts:
- Specific dates: ~D[2025-01-15]
- Date ranges: Date.range(~D[2025-01-01], ~D[2025-01-10])
- Day shortcuts: :weekends, :weekdays
- Day of month: {:day, 15} (disables 15th of every month)
- Weekday: {:weekday, 3} (disables all Wednesdays; 1=Monday, 7=Sunday)
- ISO week: {:week, 33} (disables entire ISO week 33)
- Recurring annual dates: {:month_day, 12, 25} (disables December 25th every year)
- Month pattern: {:month, 4} (disables all April dates)
- Year pattern: {:year, 2025} (disables all 2025 dates)
All strategies work together (union) - a date is disabled if it matches ANY of the criteria.
Defaults to [].
allow_deselect (:boolean) - When false, prevents deselecting the current selection by clicking on it. In single mode, the selected date cannot be unselected. In multiple mode, at least one date must remain selected. In range mode, clicking the start date won't clear the range.
Defaults to true.
locale (:string) - Locale for date formatting (e.g., 'en', 'es', 'fr', 'de', 'pt-BR'). Localizes weekday abbreviations, month names, navigation labels, time picker labels, and confirmation buttons. Unsupported locales fall back to English. Defaults to "en".
presets (:list) - List of preset date shortcuts displayed as a sidebar next to the calendar.
Each preset is a tuple with the label as the first element:
- Single date: {"Today", ~D[2026-02-28]} or {"Today", Date.utc_today()}
- Date range: {"This week", ~D[2026-02-24], ~D[2026-02-28]}
Defaults to [].
time_format (:string) - The time format to use:
- "12": 12-hour format with AM/PM selection
- "24": 24-hour format
Defaults to "12".
display_format (:string) - The format string used to display the selected date in the toggle button. Uses strftime format. Common 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)
Defaults to "%b %-d %I:%M %p".

Slots

inner_prefix - Content placed inside the date picker field's border, before the date display. Ideal for icons or short textual prefixes. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the inner prefix container.
outer_prefix - Content placed outside and before the date picker field. Useful for buttons, dropdowns, or other interactive elements associated with the date picker's start. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the outer prefix container.
inner_suffix - Content placed inside the date picker field's border, after the date display. Suitable for icons, clear buttons, or loading indicators. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the inner suffix container.
outer_suffix - Content placed outside and after the date picker field. Useful for action buttons or other controls related to the date picker's end. Can be used multiple times.Accepts attributes:
- class (:any) - CSS classes for styling the outer suffix container.