Fluxon.Components.DatePicker (Fluxon v3.1.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, multiple, and range selection with optional time picking, configurable granularity (day, month, year), multiple navigation styles, min/max constraints, flexible disabled-date patterns, a typeable text input mode, localized labels, and roving-focus keyboard navigation.

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 Fluxon.Components.Calendar when the calendar should always be visible on the page. Use DatePicker when you need a compact input that opens a calendar dropdown.

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"
  hour_cycle="h12"
  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"
/>

Typeable Input

Replace the toggle button with a 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" />

Typeable Mode Constraints

Typeable mode requires single date selection with day granularity. It is not supported with multiple, range, or granularity="month" / "year". Using typeable with an unsupported mode emits a compile-time warning and the toggle falls back to the standard button.

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	Use Case
`day`	7-column, 6 weeks	Month	`2025-01-15`	Appointments, deadlines
`month`	3-column, 12 months	Year	`2025-03`	Billing periods, expiry dates
`year`	3-column, 12 years	Decade	`2025`	Fiscal years, birth years

Selected dates are normalized to the start of the period: first of the 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

The navigation attribute controls the calendar header UI. Choose based on how much control users need over time traversal:

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

Style	Controls	Use Case
`default`	Previous/next month buttons with month-year title	Most pickers where dates are near the current month
`extended`	Adds previous/next year buttons	Booking flows that span multiple years
`select`	Month and year dropdown selects with previous/next buttons	Birth-date pickers or historical date selection

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

Once the dropdown is open, the calendar grid is fully keyboard navigable. Arrow keys move the focused cell (left/right by one day, month, or year depending on granularity, up/down by a full row), Home and End jump to the first and last day of the week, and Page Up / Page Down step the visible month. Enter or Space selects the focused cell. Focus moves cell to cell without changing the selection until a cell is chosen, and any date disabled by min, max, or disabled_dates is skipped so keyboard motion always lands on a selectable date.

Multi-Month Layout

The months attribute declares the maximum number of month grids the dropdown may render side-by-side (1..4, default 1). The actual count adapts to the viewport so the picker stays usable from phones to ultra-wide displays:

<!-- Hotel-reservation style: two months side-by-side on tablets and up -->
<.date_range_picker start_name="check_in" end_name="check_out" months={2} />

<!-- Longer planning windows: up to four months on wide displays -->
<.date_range_picker start_name="start" end_name="end" months={4} />

Viewport	Visible grids
`< 640px` (mobile)	1
`< 1024px`	up to 2
`< 1280px`	up to 3
`>= 1280px`	up to 4

A single set of previous/next arrows shifts every visible grid by exactly one month. Range selection, keyboard navigation, presets, time picker, and confirm-mode all work across grids. Only takes effect when granularity is "day" and navigation is "default" or "extended"; other combinations emit a warning and collapse to a single grid.

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 and 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" hour_cycle="h12" />
<.date_time_picker name="meeting" label="Meeting" hour_cycle="h23" />

The time interface provides hour, minute, and second inputs with direct keyboard entry, arrow-key increment and decrement, and AM/PM toggle via the a and 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

Time values follow the same wall-clock model as dates. See the Time Zones section for handling users outside UTC.

Time Zones

The picker is a wall-clock component. It emits and consumes the exact date and time the user sees, with no timezone attached, the same way the native datetime-local input behaves. Selected values are never converted across time zones, so what the user picks is what your handle_event receives. This keeps the component predictable and leaves timezone handling to your application at two boundaries: the value you send in, and the value you receive back.

The highlighted "today" needs no configuration: when today is omitted the client highlights the browser's local date, correct for the user's time zone for single-locale and multi-zone apps alike. Set today only when the server must control the value: deterministic rendering (tests, screenshots) or anchoring to a non-clock date such as a business "today".

Time-zone-aware constraints

min, max, and disabled_dates are wall-clock values, enforced exactly as you pass them. When a bound is relative to the current day (for example "today or later"), compute it in the user's time zone so it matches the day they see. The usual setup sends the browser time zone through connect params and resolves it on the server, where the same timezone also serves "Receiving the value" below:

// app.js
let liveSocket = new LiveSocket("/live", Socket, {
  params: {
    _csrf_token: csrfToken,
    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
  }
})

# In your LiveView mount/3
def mount(_params, _session, socket) do
  timezone = Phoenix.LiveView.get_connect_params(socket)["timezone"] || "Etc/UTC"
  today = DateTime.now!(timezone) |> DateTime.to_date()
  {:ok, assign(socket, timezone: timezone, today: today)}
end

<.date_picker name="date" min={@today} />

Receiving the value

A submitted value is a wall-clock NaiveDateTime with no zone, for example ~N[2025-03-10 14:30:00], meaning "2:30 PM in the user's head". To store it as an absolute instant, interpret it in the user's zone first, then shift to UTC. Labeling it UTC directly would shift the instant for anyone outside UTC:

def handle_event("save", %{"appointment" => value}, socket) do
  naive = NaiveDateTime.from_iso8601!(value)

  utc =
    case DateTime.from_naive(naive, socket.assigns.timezone) do
      {:ok, dt} -> DateTime.shift_zone!(dt, "Etc/UTC")
      {:ambiguous, first, _second} -> DateTime.shift_zone!(first, "Etc/UTC")
      {:gap, _just_before, just_after} -> DateTime.shift_zone!(just_after, "Etc/UTC")
    end

  # persist utc...
end

The :ambiguous and :gap clauses handle daylight saving transitions, where a wall-clock time can occur twice or not at all. They require a configured time zone database such as tz.

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	Use Case
`auto`	Closes immediately after selection (default)	Single-date pickers where one click is enough
`manual`	Stays open after selection	Multi-step selections such as time picking after the date
`confirm`	Shows Cancel/Apply buttons, requires explicit confirmation	Workflows where mistakes are costly and the user should commit before applying

<.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).

The toggle opens and closes the dropdown on click, and Enter or Space does the same while it is focused. While open, focus is trapped inside the panel so Tab and Shift+Tab cycle through the header controls, day grid, and time fields and wrap at the edges rather than leaking into the surrounding form. Pressing Escape, clicking outside the panel, or completing a selection in auto mode closes the dropdown and returns focus to the toggle. In confirm mode, Escape and outside clicks discard the pending 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.

Sizes

Scale the toggle for different contexts. The selected size also drives the inner padding and the size of inner-affix icons:

<.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, suitable for most forms
`lg`	40px	Primary selections, larger touch targets
`xl`	44px	Hero sections, prominent forms

Clearable

Set clearable to render a reset button inside the field. The button appears only when a value is present and stays hidden while the field is empty or disabled. Clearing resets the underlying inputs and dispatches a change event so form bindings such as phx-change are notified:

<.date_picker name="date" label="Date" clearable placeholder="Select date" />

It works across every mode. In range mode both endpoints reset together, and in multiple mode every selected date is removed:

<.date_range_picker start_name="from" end_name="to" clearable />
<.date_picker name="dates[]" multiple clearable />
<.date_picker name="date" typeable clearable />

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. The locale also determines defaults for week_start, input_format, hour_cycle, and display_format when those attributes are not explicitly set. Unsupported locales fall back to English:

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

Supported locales: ar, bg, cs, da, de, el, en, es, fi, fr, hi, 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 (for example, via Gettext).

Examples

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"
  hour_cycle="h12"
  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"
/>

Constraining the Field Width

By default, the field fills the width of its container. To narrow only the field while keeping the label, description, and help text at their natural width, apply a width utility to any ancestor that targets [data-part=field-root]:

<div class="**:data-[part=field-root]:max-w-xs">
  <.date_picker label="Start date" name="start" />
</div>

This pattern works uniformly across all Fluxon input-shaped form components.

Summary

Components

date_picker(assigns)

Renders a date picker that opens a floating calendar dropdown from a toggle button (or a typeable text input when typeable is set).

date_range_picker(assigns)

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

date_time_picker(assigns)

Renders a date and time picker that combines calendar selection with hour, minute, second, and optional AM/PM inputs.

Components

date_picker(assigns)

Renders a date picker that opens a floating calendar dropdown from a toggle button (or a typeable text input when typeable is set).

Use this component when the field needs a compact, dropdown-driven date input. It supports single selection (default) and multiple selection (with multiple={true}), configurable granularity (day, month, year), min/max constraints, disabled-date patterns, presets, and configurable closing behavior. Bind to a Phoenix form field with field, or use name and value directly for standalone usage.

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

Attributes

field (Phoenix.HTML.FormField) - Binds the date picker to a Phoenix form field for automatic name, value, and error derivation. When provided, name and value are inferred from the form field. Validation errors display automatically when the field has been used.
name (:any) - Sets the form input name for the date picker. Required when not using the field attribute. For multiple selections, append [] to the name (e.g., "holidays[]"); the suffix is added automatically when binding to a form field with multiple={true}.
value (:any) - Sets the currently selected date value. Accepts Date, NaiveDateTime, DateTime, or ISO 8601 strings. In multiple mode, accepts a list of date values. When using field, the value is derived automatically.
typeable (:boolean) - Replaces the toggle button with a text input that accepts manually typed dates. Users type the full date using the configured input_format separator (for example, 01/15/2025); separators are inserted automatically as the user types and invalid dates are silently ignored. A small calendar button on the right still opens the dropdown.
Only supported in single-date mode with day granularity. Combining typeable with multiple, range, or non-day granularity emits a compile-time warning and falls back to the standard toggle button.
Defaults to false.
input_format (:string) - Sets 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 (for example, /, ., -).
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. For example, locale="de" defaults to "dd.mm.yyyy" and locale="sv" defaults to "yyyy-mm-dd". Invalid format strings emit a compile-time warning and fall back to the locale default.
Defaults to nil.
close (:string) - Controls when the calendar dropdown closes after a selection.
- "auto" - Closes immediately after a single selection. Best for simple single-date pickers. Coerced to "manual" when multiple or time_picker is enabled.
- "manual" - Stays open after each selection so the user can pick again or interact with the time picker.
- "confirm" - Stays open and renders Cancel and Apply buttons. The selection only commits when the user clicks Apply. Best for high-stakes selections where mistakes are costly.
Defaults to "auto". Must be one of "auto", "manual", or "confirm".
id (:any) - Sets the unique identifier for the date picker. When not provided, defaults to the form field id (if using field) or the name attribute. The id is used to generate sub-element ids like {id}-toggle, {id}-typeable-input, and {id}-calendar.
Defaults to nil.
autofocus (:boolean) - Renders the toggle (or typeable input) with the autofocus attribute, focusing the field automatically when the page loads. Useful for single-field forms or modals that should be ready for input on open.
Defaults to false.
clearable (:boolean) - Renders a clear button inside the field that resets the selected value. The button appears only when a value is present and is hidden while the field is empty or disabled. Clearing resets every underlying input (both endpoints in range mode, every date in multiple mode) and dispatches a change event on the hidden inputs so form bindings such as phx-change are notified.
Defaults to false.
min (Date) - Specifies the earliest selectable date. Dates before this boundary are visually dimmed, cannot be selected via click or keyboard, and navigation buttons are disabled when they would move past this date. Accepts Date, DateTime, or ISO 8601 date strings.
Defaults to nil.
max (Date) - Specifies the latest selectable date. Dates after this boundary are visually dimmed, cannot be selected via click or keyboard, and navigation buttons are disabled when they would move past this date. Accepts Date, DateTime, or ISO 8601 date strings.
Defaults to nil.
today (:any) - Sets the date treated as "today", which controls the highlighted current day and the default visible month when no value is selected. Accepts Date, DateTime, NaiveDateTime, or ISO 8601 strings, normalized to a Date.
When omitted, the client highlights the browser's local date, so the current day is correct for the user's time zone with no configuration. Set this to let the server control the value instead: for deterministic rendering (tests, screenshots) or anchoring to a non-clock date. See the "Time Zones" section for details.
Defaults to nil.
week_start (:integer) - Determines which day of the week appears in the first column of the day grid. When not provided, the value is derived from the component's locale.
- 0 - Sunday (common in the US and Canada)
- 1 - Monday (common in Europe and ISO 8601)
- 2 - Tuesday
- 3 - Wednesday
- 4 - Thursday
- 5 - Friday (common in some Middle Eastern locales)
- 6 - Saturday
Defaults to nil.
size (:string) - Controls the height and inner padding of the toggle, along with the size of affix icons.
- "xs" - 28px tall. Use for compact UIs and dashboard widgets.
- "sm" - 32px tall. Use for secondary inputs and sidebar forms.
- "md" - 36px tall. Default size, suitable for most forms.
- "lg" - 40px tall. Use for primary selections and larger touch targets.
- "xl" - 44px tall. Use for hero sections and prominent forms.
Defaults to "md". Must be one of "xs", "sm", "md", "lg", or "xl".
class (:any) - Additional CSS classes applied to the calendar dropdown panel (the floating wrapper that contains the calendar grid, presets, time picker, and confirmation buttons). Merged with the default styles.
Defaults to nil.
granularity (:string) - Controls the selection precision and the layout of the calendar grid. Selected values are normalized to the start of the period.
- "day" - 7-column grid showing individual days. Navigates by month. Best for appointment dates and deadlines.
- "month" - 3-column grid showing 12 months. Navigates by year. Dates normalize to the first of the month. Best for billing periods and expiry dates.
- "year" - 3-column grid showing 12 years. Navigates by decade. Dates normalize to January 1st. Best for fiscal years and birth years.
Defaults to "day". Must be one of "day", "month", or "year".
hide_outside_days (:boolean) - Controls whether the day grid fills the leading and trailing empty cells with days from the previous and next month. Only affects day granularity.
- false (default): renders a padded six-week grid, with outside-month days dimmed. The grid keeps a constant height across months.
- true: renders only the current month's days. Leading and trailing cells are left blank and full outside-month weeks are dropped, so the grid uses four to six rows depending on the month and its height changes as you navigate. With multiple months, side-by-side grids may differ in height.
Defaults to false.
navigation (:string) - Controls the navigation interface in the calendar header. Buttons and dropdown options are automatically constrained to the min/max range.
- "default" - Previous/next month arrows with a month-year title. Best for most pickers.
- "extended" - Adds previous/next year arrows for faster traversal across years. Best for booking flows that span multiple years.
- "select" - Month and year dropdown selects beside the next/previous arrows. Best for birth-date pickers or historical date selection.
Defaults to "default". Must be one of "default", "extended", or "select".
months (:integer) - Maximum number of month grids to render side-by-side in the calendar dropdown (1..4). The actual number of visible grids adapts to the viewport width and is capped at the declared maximum:
Viewport Visible grids
< 640px (mobile) 1
< 1024px up to 2
< 1280px up to 3
>= 1280px up to 4
Each visible grid shares one set of previous/next arrows that shift every grid by one month. Useful for date range pickers where users benefit from seeing multiple months at once (hotel reservations, travel booking). Only takes effect when granularity is "day" and navigation is "default" or "extended"; otherwise falls back to a single grid.
Defaults to 1.
disabled (:boolean) - Disables the entire date picker when set to true. The toggle becomes non-interactive, the dropdown will not open, and the field appears visually muted.
Defaults to false.
label (:string) - Sets the primary label text displayed above the date picker. Renders as a <label> element and is associated with the toggle (or typeable input) via the for attribute.
Defaults to nil.
sublabel (:string) - Specifies secondary text displayed inline beside the main label. Useful for adding optional context like "(optional)" or a brief clarification.
Defaults to nil.
description (:string) - Provides a longer description rendered below the label and above the date picker field. Useful for instructions or additional context about the expected selection.
Defaults to nil.
help_text (:string) - Displays helper text below the date picker field. Useful for formatting hints, selection guidance, or contextual information that the user should see while filling out the form.
Defaults to nil.
placeholder (:string) - Sets the text shown in the toggle when no date is selected. Also used as the placeholder for the typeable input when typeable is enabled.
Defaults to nil.
errors (:list) - Specifies error messages to display below the date picker field. When using the field attribute (or start_field/end_field for ranges), errors are automatically derived from form validation. Each error renders as a styled error message.
Defaults to [].
disabled_dates (:list) - Specifies dates, date ranges, or recurring patterns to disable. Disabled dates are visually dimmed with a strikethrough, cannot be selected, and keyboard navigation skips over them. Patterns combine with union logic: a date is disabled if it matches any pattern. 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} (every month)
- Weekday: {:weekday, 3} (1=Monday, 7=Sunday)
- ISO week: {:week, 33}
- Recurring annual dates: {:month_day, 12, 25}
- Month pattern: {:month, 4} (entire month, every year)
- Year pattern: {:year, 2025} (entire year)
Defaults to [].
allow_deselect (:boolean) - Controls whether clicking an already-selected date deselects it. Defaults to true.
- In single mode, clicking the selected date clears the value.
- In multiple mode, at least one date must remain selected when false.
- In range mode, clicking the start date of a complete range will not clear both values when false.
Set to false when a selection is always required.
Defaults to true.
locale (:string) - Sets the locale for localizing weekday abbreviations, month names, navigation labels, time picker labels, and confirmation buttons. Defaults to "en". The locale also drives defaults for week_start, input_format, hour_cycle, and display_format when those attributes are not explicitly set. Unsupported locales fall back to English.
Supports a wide range of languages including ar, de, es, fr, ja, ko, pt-BR, zh, and others.
Defaults to "en".
presets (:list) - Renders a sidebar of preset date shortcuts beside the calendar grid. Clicking a preset selects the date(s) and navigates the calendar to the matching view. The active preset is highlighted when it matches the current selection. In confirm mode, preset selections are pending until Apply is clicked.
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 (for date_range_picker): {"This week", ~D[2026-02-24], ~D[2026-02-28]}
Defaults to [].
on_open (Phoenix.LiveView.JS) - Phoenix.LiveView.JS commands to run after the picker dropdown finishes opening (after the enter animation completes).
Defaults to %Phoenix.LiveView.JS{ops: []}.
on_close (Phoenix.LiveView.JS) - Phoenix.LiveView.JS commands to run after the picker dropdown finishes closing (after the leave animation completes).
Defaults to %Phoenix.LiveView.JS{ops: []}.
multiple (:boolean) - Enables multiple-date selection when set to true. Each click toggles a date on or off, the calendar stays open after each selection, and the toggle text shows a "X dates selected" summary. The form submits an array of dates; one hidden input is rendered per selected date. Append [] to the name for proper array parameter parsing.
Defaults to false.
display_format (:string) - Sets the strftime format used to display the selected date(s) in the toggle. When not provided, the format is derived from the locale and adapts to the granularity (month-only or year-only formats are used for non-day granularities unless overridden).
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)
Time directives (%H, %I, %M, %p) should only be used with date_time_picker/1. See strftime/3 for the full list of directives.
Defaults to nil.

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 a start date and end date pair.

Use this component for booking flows, reservation periods, reporting windows, or any scenario where two related dates must be captured together. The first click sets the start date, the second click sets the end date, and dates between the two are visually highlighted. Bind a pair of form fields with start_field and end_field, or use start_name/end_name with start_value/end_value for standalone usage. Two hidden inputs are rendered for form submission, one per endpoint.

<.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) - Binds the range start date to a Phoenix form field. When provided, start_name and start_value are inferred from the field. Validation errors from both start and end fields are collected and displayed together. Must be used with end_field.
end_field (Phoenix.HTML.FormField) - Binds the range end date to a Phoenix form field. When provided, end_name and end_value are inferred from the field. Must be used with start_field.
start_name (:any) - Sets the form input name for the start date. Required when not using start_field. The hidden input for the start date uses this name for form submission.
end_name (:any) - Sets the form input name for the end date. Required when not using end_field. The hidden input for the end date uses this name for form submission.
start_value (:any) - Sets the initial start date for the range. Accepts Date, NaiveDateTime, DateTime, or ISO 8601 strings. The start date is highlighted at the beginning of the visual range.
end_value (:any) - Sets the initial end date for the range. Accepts Date, NaiveDateTime, DateTime, or ISO 8601 strings. The end date is highlighted at the end of the visual range.
close (:string) - Controls when the calendar dropdown closes after a selection.
- "manual" (default) - Stays open after each selection so the user can refine the start, end, or jump to a different month. Best when a typeable input or presets sit alongside the calendar.
- "auto" - Closes once both endpoints are picked. Best for compact flows where the next step depends on the completed range.
- "confirm" - Stays open and renders Cancel and Apply buttons. The selection only commits when the user clicks Apply.
Defaults to "manual". Must be one of "auto", "manual", or "confirm".
id (:any) - Sets the unique identifier for the date picker. When not provided, defaults to the form field id (if using field) or the name attribute. The id is used to generate sub-element ids like {id}-toggle, {id}-typeable-input, and {id}-calendar.
Defaults to nil.
autofocus (:boolean) - Renders the toggle (or typeable input) with the autofocus attribute, focusing the field automatically when the page loads. Useful for single-field forms or modals that should be ready for input on open.
Defaults to false.
clearable (:boolean) - Renders a clear button inside the field that resets the selected value. The button appears only when a value is present and is hidden while the field is empty or disabled. Clearing resets every underlying input (both endpoints in range mode, every date in multiple mode) and dispatches a change event on the hidden inputs so form bindings such as phx-change are notified.
Defaults to false.
min (Date) - Specifies the earliest selectable date. Dates before this boundary are visually dimmed, cannot be selected via click or keyboard, and navigation buttons are disabled when they would move past this date. Accepts Date, DateTime, or ISO 8601 date strings.
Defaults to nil.
max (Date) - Specifies the latest selectable date. Dates after this boundary are visually dimmed, cannot be selected via click or keyboard, and navigation buttons are disabled when they would move past this date. Accepts Date, DateTime, or ISO 8601 date strings.
Defaults to nil.
today (:any) - Sets the date treated as "today", which controls the highlighted current day and the default visible month when no value is selected. Accepts Date, DateTime, NaiveDateTime, or ISO 8601 strings, normalized to a Date.
When omitted, the client highlights the browser's local date, so the current day is correct for the user's time zone with no configuration. Set this to let the server control the value instead: for deterministic rendering (tests, screenshots) or anchoring to a non-clock date. See the "Time Zones" section for details.
Defaults to nil.
week_start (:integer) - Determines which day of the week appears in the first column of the day grid. When not provided, the value is derived from the component's locale.
- 0 - Sunday (common in the US and Canada)
- 1 - Monday (common in Europe and ISO 8601)
- 2 - Tuesday
- 3 - Wednesday
- 4 - Thursday
- 5 - Friday (common in some Middle Eastern locales)
- 6 - Saturday
Defaults to nil.
size (:string) - Controls the height and inner padding of the toggle, along with the size of affix icons.
- "xs" - 28px tall. Use for compact UIs and dashboard widgets.
- "sm" - 32px tall. Use for secondary inputs and sidebar forms.
- "md" - 36px tall. Default size, suitable for most forms.
- "lg" - 40px tall. Use for primary selections and larger touch targets.
- "xl" - 44px tall. Use for hero sections and prominent forms.
Defaults to "md". Must be one of "xs", "sm", "md", "lg", or "xl".
class (:any) - Additional CSS classes applied to the calendar dropdown panel (the floating wrapper that contains the calendar grid, presets, time picker, and confirmation buttons). Merged with the default styles.
Defaults to nil.
granularity (:string) - Controls the selection precision and the layout of the calendar grid. Selected values are normalized to the start of the period.
- "day" - 7-column grid showing individual days. Navigates by month. Best for appointment dates and deadlines.
- "month" - 3-column grid showing 12 months. Navigates by year. Dates normalize to the first of the month. Best for billing periods and expiry dates.
- "year" - 3-column grid showing 12 years. Navigates by decade. Dates normalize to January 1st. Best for fiscal years and birth years.
Defaults to "day". Must be one of "day", "month", or "year".
hide_outside_days (:boolean) - Controls whether the day grid fills the leading and trailing empty cells with days from the previous and next month. Only affects day granularity.
- false (default): renders a padded six-week grid, with outside-month days dimmed. The grid keeps a constant height across months.
- true: renders only the current month's days. Leading and trailing cells are left blank and full outside-month weeks are dropped, so the grid uses four to six rows depending on the month and its height changes as you navigate. With multiple months, side-by-side grids may differ in height.
Defaults to false.
navigation (:string) - Controls the navigation interface in the calendar header. Buttons and dropdown options are automatically constrained to the min/max range.
- "default" - Previous/next month arrows with a month-year title. Best for most pickers.
- "extended" - Adds previous/next year arrows for faster traversal across years. Best for booking flows that span multiple years.
- "select" - Month and year dropdown selects beside the next/previous arrows. Best for birth-date pickers or historical date selection.
Defaults to "default". Must be one of "default", "extended", or "select".
months (:integer) - Maximum number of month grids to render side-by-side in the calendar dropdown (1..4). The actual number of visible grids adapts to the viewport width and is capped at the declared maximum:
Viewport Visible grids
< 640px (mobile) 1
< 1024px up to 2
< 1280px up to 3
>= 1280px up to 4
Each visible grid shares one set of previous/next arrows that shift every grid by one month. Useful for date range pickers where users benefit from seeing multiple months at once (hotel reservations, travel booking). Only takes effect when granularity is "day" and navigation is "default" or "extended"; otherwise falls back to a single grid.
Defaults to 1.
disabled (:boolean) - Disables the entire date picker when set to true. The toggle becomes non-interactive, the dropdown will not open, and the field appears visually muted.
Defaults to false.
label (:string) - Sets the primary label text displayed above the date picker. Renders as a <label> element and is associated with the toggle (or typeable input) via the for attribute.
Defaults to nil.
sublabel (:string) - Specifies secondary text displayed inline beside the main label. Useful for adding optional context like "(optional)" or a brief clarification.
Defaults to nil.
description (:string) - Provides a longer description rendered below the label and above the date picker field. Useful for instructions or additional context about the expected selection.
Defaults to nil.
help_text (:string) - Displays helper text below the date picker field. Useful for formatting hints, selection guidance, or contextual information that the user should see while filling out the form.
Defaults to nil.
placeholder (:string) - Sets the text shown in the toggle when no date is selected. Also used as the placeholder for the typeable input when typeable is enabled.
Defaults to nil.
errors (:list) - Specifies error messages to display below the date picker field. When using the field attribute (or start_field/end_field for ranges), errors are automatically derived from form validation. Each error renders as a styled error message.
Defaults to [].
disabled_dates (:list) - Specifies dates, date ranges, or recurring patterns to disable. Disabled dates are visually dimmed with a strikethrough, cannot be selected, and keyboard navigation skips over them. Patterns combine with union logic: a date is disabled if it matches any pattern. 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} (every month)
- Weekday: {:weekday, 3} (1=Monday, 7=Sunday)
- ISO week: {:week, 33}
- Recurring annual dates: {:month_day, 12, 25}
- Month pattern: {:month, 4} (entire month, every year)
- Year pattern: {:year, 2025} (entire year)
Defaults to [].
allow_deselect (:boolean) - Controls whether clicking an already-selected date deselects it. Defaults to true.
- In single mode, clicking the selected date clears the value.
- In multiple mode, at least one date must remain selected when false.
- In range mode, clicking the start date of a complete range will not clear both values when false.
Set to false when a selection is always required.
Defaults to true.
locale (:string) - Sets the locale for localizing weekday abbreviations, month names, navigation labels, time picker labels, and confirmation buttons. Defaults to "en". The locale also drives defaults for week_start, input_format, hour_cycle, and display_format when those attributes are not explicitly set. Unsupported locales fall back to English.
Supports a wide range of languages including ar, de, es, fr, ja, ko, pt-BR, zh, and others.
Defaults to "en".
presets (:list) - Renders a sidebar of preset date shortcuts beside the calendar grid. Clicking a preset selects the date(s) and navigates the calendar to the matching view. The active preset is highlighted when it matches the current selection. In confirm mode, preset selections are pending until Apply is clicked.
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 (for date_range_picker): {"This week", ~D[2026-02-24], ~D[2026-02-28]}
Defaults to [].
on_open (Phoenix.LiveView.JS) - Phoenix.LiveView.JS commands to run after the picker dropdown finishes opening (after the enter animation completes).
Defaults to %Phoenix.LiveView.JS{ops: []}.
on_close (Phoenix.LiveView.JS) - Phoenix.LiveView.JS commands to run after the picker dropdown finishes closing (after the leave animation completes).
Defaults to %Phoenix.LiveView.JS{ops: []}.
display_format (:string) - Sets the strftime format used to display the selected date range in the toggle. Both endpoints are formatted with the same pattern and joined by a separator. When not provided, the format is derived from the locale.
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)
See strftime/3 for the full list of format directives.
Defaults to nil.

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 and time picker that combines calendar selection with hour, minute, second, and optional AM/PM inputs.

Use this component when the field needs both a date and a time, such as appointments, meetings, or scheduled events. It is functionally equivalent to date_picker/1 with time_picker={true}, with the hour_cycle and display_format defaults adjusted to include time. Requires a NaiveDateTime or DateTime field on the schema; the component treats all values as UTC.

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

Attributes

field (Phoenix.HTML.FormField) - Binds the date picker to a Phoenix form field for automatic name, value, and error derivation. When provided, name and value are inferred from the form field. Validation errors display automatically when the field has been used.
name (:any) - Sets the form input name for the date picker. Required when not using the field attribute. For multiple selections, append [] to the name (e.g., "holidays[]"); the suffix is added automatically when binding to a form field with multiple={true}.
value (:any) - Sets the currently selected date value. Accepts Date, NaiveDateTime, DateTime, or ISO 8601 strings. In multiple mode, accepts a list of date values. When using field, the value is derived automatically.
typeable (:boolean) - Replaces the toggle button with a text input that accepts manually typed dates. Users type the full date using the configured input_format separator (for example, 01/15/2025); separators are inserted automatically as the user types and invalid dates are silently ignored. A small calendar button on the right still opens the dropdown.
Only supported in single-date mode with day granularity. Combining typeable with multiple, range, or non-day granularity emits a compile-time warning and falls back to the standard toggle button.
Defaults to false.
input_format (:string) - Sets 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 (for example, /, ., -).
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. For example, locale="de" defaults to "dd.mm.yyyy" and locale="sv" defaults to "yyyy-mm-dd". Invalid format strings emit a compile-time warning and fall back to the locale default.
Defaults to nil.
close (:string) - Controls when the calendar dropdown closes after a selection.
- "auto" - Closes immediately after a single selection. Best for simple single-date pickers. Coerced to "manual" when multiple or time_picker is enabled.
- "manual" - Stays open after each selection so the user can pick again or interact with the time picker.
- "confirm" - Stays open and renders Cancel and Apply buttons. The selection only commits when the user clicks Apply. Best for high-stakes selections where mistakes are costly.
Defaults to "auto". Must be one of "auto", "manual", or "confirm".
id (:any) - Sets the unique identifier for the date picker. When not provided, defaults to the form field id (if using field) or the name attribute. The id is used to generate sub-element ids like {id}-toggle, {id}-typeable-input, and {id}-calendar.
Defaults to nil.
autofocus (:boolean) - Renders the toggle (or typeable input) with the autofocus attribute, focusing the field automatically when the page loads. Useful for single-field forms or modals that should be ready for input on open.
Defaults to false.
clearable (:boolean) - Renders a clear button inside the field that resets the selected value. The button appears only when a value is present and is hidden while the field is empty or disabled. Clearing resets every underlying input (both endpoints in range mode, every date in multiple mode) and dispatches a change event on the hidden inputs so form bindings such as phx-change are notified.
Defaults to false.
min (Date) - Specifies the earliest selectable date. Dates before this boundary are visually dimmed, cannot be selected via click or keyboard, and navigation buttons are disabled when they would move past this date. Accepts Date, DateTime, or ISO 8601 date strings.
Defaults to nil.
max (Date) - Specifies the latest selectable date. Dates after this boundary are visually dimmed, cannot be selected via click or keyboard, and navigation buttons are disabled when they would move past this date. Accepts Date, DateTime, or ISO 8601 date strings.
Defaults to nil.
today (:any) - Sets the date treated as "today", which controls the highlighted current day and the default visible month when no value is selected. Accepts Date, DateTime, NaiveDateTime, or ISO 8601 strings, normalized to a Date.
When omitted, the client highlights the browser's local date, so the current day is correct for the user's time zone with no configuration. Set this to let the server control the value instead: for deterministic rendering (tests, screenshots) or anchoring to a non-clock date. See the "Time Zones" section for details.
Defaults to nil.
week_start (:integer) - Determines which day of the week appears in the first column of the day grid. When not provided, the value is derived from the component's locale.
- 0 - Sunday (common in the US and Canada)
- 1 - Monday (common in Europe and ISO 8601)
- 2 - Tuesday
- 3 - Wednesday
- 4 - Thursday
- 5 - Friday (common in some Middle Eastern locales)
- 6 - Saturday
Defaults to nil.
size (:string) - Controls the height and inner padding of the toggle, along with the size of affix icons.
- "xs" - 28px tall. Use for compact UIs and dashboard widgets.
- "sm" - 32px tall. Use for secondary inputs and sidebar forms.
- "md" - 36px tall. Default size, suitable for most forms.
- "lg" - 40px tall. Use for primary selections and larger touch targets.
- "xl" - 44px tall. Use for hero sections and prominent forms.
Defaults to "md". Must be one of "xs", "sm", "md", "lg", or "xl".
class (:any) - Additional CSS classes applied to the calendar dropdown panel (the floating wrapper that contains the calendar grid, presets, time picker, and confirmation buttons). Merged with the default styles.
Defaults to nil.
granularity (:string) - Controls the selection precision and the layout of the calendar grid. Selected values are normalized to the start of the period.
- "day" - 7-column grid showing individual days. Navigates by month. Best for appointment dates and deadlines.
- "month" - 3-column grid showing 12 months. Navigates by year. Dates normalize to the first of the month. Best for billing periods and expiry dates.
- "year" - 3-column grid showing 12 years. Navigates by decade. Dates normalize to January 1st. Best for fiscal years and birth years.
Defaults to "day". Must be one of "day", "month", or "year".
hide_outside_days (:boolean) - Controls whether the day grid fills the leading and trailing empty cells with days from the previous and next month. Only affects day granularity.
- false (default): renders a padded six-week grid, with outside-month days dimmed. The grid keeps a constant height across months.
- true: renders only the current month's days. Leading and trailing cells are left blank and full outside-month weeks are dropped, so the grid uses four to six rows depending on the month and its height changes as you navigate. With multiple months, side-by-side grids may differ in height.
Defaults to false.
navigation (:string) - Controls the navigation interface in the calendar header. Buttons and dropdown options are automatically constrained to the min/max range.
- "default" - Previous/next month arrows with a month-year title. Best for most pickers.
- "extended" - Adds previous/next year arrows for faster traversal across years. Best for booking flows that span multiple years.
- "select" - Month and year dropdown selects beside the next/previous arrows. Best for birth-date pickers or historical date selection.
Defaults to "default". Must be one of "default", "extended", or "select".
months (:integer) - Maximum number of month grids to render side-by-side in the calendar dropdown (1..4). The actual number of visible grids adapts to the viewport width and is capped at the declared maximum:
Viewport Visible grids
< 640px (mobile) 1
< 1024px up to 2
< 1280px up to 3
>= 1280px up to 4
Each visible grid shares one set of previous/next arrows that shift every grid by one month. Useful for date range pickers where users benefit from seeing multiple months at once (hotel reservations, travel booking). Only takes effect when granularity is "day" and navigation is "default" or "extended"; otherwise falls back to a single grid.
Defaults to 1.
disabled (:boolean) - Disables the entire date picker when set to true. The toggle becomes non-interactive, the dropdown will not open, and the field appears visually muted.
Defaults to false.
label (:string) - Sets the primary label text displayed above the date picker. Renders as a <label> element and is associated with the toggle (or typeable input) via the for attribute.
Defaults to nil.
sublabel (:string) - Specifies secondary text displayed inline beside the main label. Useful for adding optional context like "(optional)" or a brief clarification.
Defaults to nil.
description (:string) - Provides a longer description rendered below the label and above the date picker field. Useful for instructions or additional context about the expected selection.
Defaults to nil.
help_text (:string) - Displays helper text below the date picker field. Useful for formatting hints, selection guidance, or contextual information that the user should see while filling out the form.
Defaults to nil.
placeholder (:string) - Sets the text shown in the toggle when no date is selected. Also used as the placeholder for the typeable input when typeable is enabled.
Defaults to nil.
errors (:list) - Specifies error messages to display below the date picker field. When using the field attribute (or start_field/end_field for ranges), errors are automatically derived from form validation. Each error renders as a styled error message.
Defaults to [].
disabled_dates (:list) - Specifies dates, date ranges, or recurring patterns to disable. Disabled dates are visually dimmed with a strikethrough, cannot be selected, and keyboard navigation skips over them. Patterns combine with union logic: a date is disabled if it matches any pattern. 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} (every month)
- Weekday: {:weekday, 3} (1=Monday, 7=Sunday)
- ISO week: {:week, 33}
- Recurring annual dates: {:month_day, 12, 25}
- Month pattern: {:month, 4} (entire month, every year)
- Year pattern: {:year, 2025} (entire year)
Defaults to [].
allow_deselect (:boolean) - Controls whether clicking an already-selected date deselects it. Defaults to true.
- In single mode, clicking the selected date clears the value.
- In multiple mode, at least one date must remain selected when false.
- In range mode, clicking the start date of a complete range will not clear both values when false.
Set to false when a selection is always required.
Defaults to true.
locale (:string) - Sets the locale for localizing weekday abbreviations, month names, navigation labels, time picker labels, and confirmation buttons. Defaults to "en". The locale also drives defaults for week_start, input_format, hour_cycle, and display_format when those attributes are not explicitly set. Unsupported locales fall back to English.
Supports a wide range of languages including ar, de, es, fr, ja, ko, pt-BR, zh, and others.
Defaults to "en".
presets (:list) - Renders a sidebar of preset date shortcuts beside the calendar grid. Clicking a preset selects the date(s) and navigates the calendar to the matching view. The active preset is highlighted when it matches the current selection. In confirm mode, preset selections are pending until Apply is clicked.
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 (for date_range_picker): {"This week", ~D[2026-02-24], ~D[2026-02-28]}
Defaults to [].
on_open (Phoenix.LiveView.JS) - Phoenix.LiveView.JS commands to run after the picker dropdown finishes opening (after the enter animation completes).
Defaults to %Phoenix.LiveView.JS{ops: []}.
on_close (Phoenix.LiveView.JS) - Phoenix.LiveView.JS commands to run after the picker dropdown finishes closing (after the leave animation completes).
Defaults to %Phoenix.LiveView.JS{ops: []}.
hour_cycle (:string) - Selects the hour cycle for the time picker, following CLDR conventions.
- "h12" - 12-hour format with an AM/PM selector. Best for English-speaking locales.
- "h23" - 24-hour format. Best for most non-English locales and technical contexts.
When not provided, the value is derived from the locale. For example, locale="de" defaults to "h23" while locale="en" defaults to "h12".
Defaults to nil.
time_format (:string) - Deprecated. Use hour_cycle instead. Accepts "12" or "24" for backwards compatibility; values are mapped to the equivalent hour_cycle value with a runtime warning.
Defaults to nil.
display_format (:string) - Sets the strftime format used to display the selected date and time in the toggle. When not provided, the format is derived from the locale and defaults to a date-and-time pattern such as "%b %-d %I:%M %p".
Common patterns:
- "%Y-%m-%d %H:%M:%S" - ISO format with 24-hour time (2024-01-01 14:30:00)
- "%B %-d, %Y at %I:%M %p" - Full month with 12-hour time (January 1, 2024 at 02:30 PM)
- "%d/%m/%Y %H:%M" - European format with 24-hour time (01/01/2024 14:30)
- "%m/%d/%Y %I:%M %p" - US format with 12-hour time (01/01/2024 02:30 PM)
- "%a, %b %-d at %I:%M %p" - Short format (Mon, Jan 1 at 02:30 PM)
See strftime/3 for the full list of format directives.
Defaults to nil.

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.