# Date Picker **A calendar for picking a single date, several dates, or a range of dates.** **Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/DatePicker) · [Zag.js Docs](https://zagjs.com/components/react/date-picker) **DatePickerExamples.html** ```html Date ``` ## Features - Single, multiple, and range selection - Day, month, and year views, switched from the calendar heading, or a picker for months or years only - Dates can be typed into the input, in the format of the `locale` - Keyboard navigation with the arrow keys, `Home`, `End`, `PageUp`, and `PageDown` - Minimum and maximum dates, and a check for dates that are unavailable - Range presets, like "last 7 days" - Formats dates and localizes its labels for the site language - Submits dates Extbase maps to a `DateTime`, whatever format the input shows - Works with Field component for form integration - Opens in a popup, or renders inline without one ## Anatomy ```html ``` The calendar has three views: `day`, `month`, and `year`. The `content` only holds what you put into it, so you render the views you need yourself, each in a `view` with its controls and its `table`. Every example on this page loops over the views; write them out one by one if the views differ. The `tableHeader` and `tableBody` belong to the `table` they sit in. Its cells, the weekday headings, and the options of `monthSelect` and `yearSelect` are not part of the markup you write: they depend on the locale and on the month shown, so the client builds them. Because of that, the grid of an `inline` date picker is empty until it hydrates: `showSkeleton="{true}"` on the `tableHeader` and the `tableBody` of the day view fills the gap with a placeholder (see [Inline](#inline)). ## Installation ```bash typo3 ui:add date-picker ``` Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Registry/DatePicker) into your project. Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md). ## Examples ### Default Value Pass `defaultValue` as an ISO date (`2025-06-15`), a `DateTimeInterface`, or a list of them. A Field inside a Form that is bound to an object takes the value of the property the field is named after. **DatePickerExamples.html** ```html Date ``` ### With Form Field Use with the Field component for form validation. **DatePickerExamples.html** ```html Date of birth ``` ### Range Selection Set `selectionMode` to `DatePickerSelectionMode::Range` (an enum, so `selectionMode="{f:constant(name: 'Jramke\FluidPrimitives\Enum\DatePickerSelectionMode::Range')}"`) and add an `input` for each end of the range with its `index`. The `presetTrigger` selects a range with one click. Its `value` is a case of the `DatePickerRangePreset` enum (`value="{f:constant(name: 'Jramke\FluidPrimitives\Enum\DatePickerRangePreset::Last7Days')}"`): `ThisWeek`, `LastWeek`, `ThisMonth`, `LastMonth`, `ThisQuarter`, `LastQuarter`, `ThisYear`, `LastYear`, `Last3Days`, `Last7Days`, `Last14Days`, `Last30Days`, or `Last90Days`. **DatePickerExamples.html** ```html Stay –
This week This month Last 7 days
``` ### Multiple Selection Set `selectionMode` to `DatePickerSelectionMode::Multiple` and limit the number of dates with `maxSelectedDates`. The input shows the first date only, so the example lists all of them below it, with an `onValueChange` callback it gives the `DatePicker` in its entry file (see [Unavailable Dates](#unavailable-dates)). **DatePickerExamples.html** ```html Dates (up to 3)

No dates selected

 ``` **Multiple.entry.ts** ```ts import { mount } from 'fluid-primitives'; import { DatePicker } from 'fluid-primitives/date-picker'; mount('ui:datePicker', 'date-picker-multiple', ({ props }) => { const datePicker = new DatePicker({ ...props, // The input shows the first date only, so every selected date is listed below it. onValueChange: ({ valueAsString }) => { const datesEl = document.getElementById('date-picker-multiple-dates'); if (datesEl) datesEl.textContent = valueAsString.join(', ') || 'No dates selected'; }, }); datePicker.init(); return datePicker; }); ``` ### Multiple Months `numOfMonths` shows several months of the day view next to each other. Render one `table` per month in the day view, with the `offset` of the month it shows (`0` for the first, `1` for the next). The example keeps the offsets in a `months` variable, so the same list sets `numOfMonths` and drives the loop. The month and year views always show a single table. The `ui` copy of `content` hides the days outside the visible month when `numOfMonths` is above `1`, so no day shows up in two neighbouring months. **DatePickerExamples.html** ```html Stay –
``` ### Min/Max Constraints Restrict the dates that can be selected with `min` and `max`, each an ISO date (`2025-06-15`) or a `DateTimeInterface`, like a date of your model. `defaultFocusedValue` takes the same. **DatePickerExamples.html** ```html Appointment (within the next 30 days) ``` ### Inline Render the calendar in the page, without a popup, with `inline="{true}"`. It is always open and needs no `control`. **DatePickerExamples.html** ```html ``` ### Unavailable Dates `isDateUnavailable`, `format`, `parse`, `createCalendar`, and the `on...Change` callbacks are functions, so a template can't pass them. Create the `DatePicker` in your entry file instead and hand them to it with the other props. Here the weekends are unavailable. **DatePickerExamples.html** ```html Delivery date ``` **UnavailableDates.entry.ts** ```ts import { isWeekend } from '@internationalized/date'; import { mount } from 'fluid-primitives'; import { DatePicker } from 'fluid-primitives/date-picker'; mount('ui:datePicker', 'date-picker-unavailable-dates', ({ props }) => { const datePicker = new DatePicker({ ...props, // A function can't travel from the template to the client, so it is passed here. isDateUnavailable: (date, locale) => isWeekend(date, locale), }); datePicker.init(); return datePicker; }); ``` ### Month and Year Picker Set `minView` to `DatePickerView::Month` to pick a month instead of a day, and `defaultView` to open on the month view. The picked month is its first day, so the `hiddenInput` submits the first of the month. Render only the views the calendar can reach: the day view is left out here. `format` and `parse` turn the input into `06/2025` and read it back. They are functions, so they come from the entry file as in [Unavailable Dates](#unavailable-dates), and `placeholder` tells people what to type. **DatePickerExamples.html** ```html Card expires ``` **MonthYear.entry.ts** ```ts import { CalendarDate } from '@internationalized/date'; import { mount } from 'fluid-primitives'; import { DatePicker } from 'fluid-primitives/date-picker'; mount('ui:datePicker', 'date-picker-month-year', ({ props }) => { const datePicker = new DatePicker({ ...props, // The input shows `06/2025`, the hidden input still submits the first of the month (`2025-06-01`). format: date => `${String(date.month).padStart(2, '0')}/${date.year}`, parse: value => { const match = /^(\d{1,2})\/(\d{4})$/.exec(value); if (!match) return undefined; const month = Number(match[1]); return month >= 1 && month <= 12 ? new CalendarDate(Number(match[2]), month, 1) : undefined; }, }); datePicker.init(); return datePicker; }); ``` For a year picker, use `DatePickerView::Year` for `minView` and `defaultView`, render the `year` view only, and let `format` return `String(date.year)` and `parse` return `new CalendarDate(year, 1, 1)`. ### Dates in forms The `hiddenInput` submits each selected date as the W3C date-time of its midnight (`2025-06-15T00:00:00+02:00`), whatever format the `locale` shows it in. The visible `input` has no `name` and is not submitted, and `ui:datePicker.root` renders the `hiddenInput` for you. A range or several dates submit one value per date under the same `name`, so end the name with `[]` (`dates[]`) for PHP to receive all of them. A date picker without a date submits an empty value. That is the format Extbase maps to a `DateTime` property without any configuration. The offset is the one of the time zone PHP runs in, so the property holds the date that was picked: Extbase converts any other offset to that time zone, which can move the date to the day before or after. Extbase maps a request value to a `DateTime` only: it reads a `DateTimeImmutable` from the database, but has no type converter for one from a request. Type the property `DateTime`, or write a custom type converter for `DateTimeImmutable` if you need it. Outside Extbase, `new DateTimeImmutable($_POST['date'])` reads the value. ### Time zone The calendar works in the time zone of the browser: it highlights today for the person looking at it, and the presets and `min`/`max` count from there. Zag falls back to UTC without a `timeZone`, which highlights the wrong day for a few hours of the day almost everywhere, so Fluid Primitives replaces that default. Set `timeZone` (`Europe/Berlin`) to use another one, like the time zone of a venue. The submitted dates carry the offset of the time zone PHP runs in, whatever `timeZone` is, so it never changes what is submitted. ### Localization Dates are formatted for the language of the site, or for the `locale` you pass. Every label, from the buttons and the day cells to the month and year select and the placeholder of the input, is shipped via XLF in English and German and follows the current Site Language. They are the `datePicker.*` units of the language file. Some contain a `%placeholder%` that is filled in when the label renders, like the `%date%` of a day cell. For per-template overrides, pass translated strings through the `translations` prop, by the id of the unit without `datePicker.`. ```html ... ``` The client builds the labels Zag wants as functions of the date or the view from these texts. To change one of those from TypeScript, spread the translations your entry file receives and override it the way Zag takes it: ```ts const datePicker = new DatePicker({ ...props, translations: { ...props.translations, dayCell: state => `Pick ${state.valueText}` }, }); ``` ## API Reference ### datePicker.root Provides shared date picker state and wraps all related parts. Renders a `
` element. | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `locale` | `string` | No | `-` | The locale (BCP 47 language tag) used to format and parse dates. Inherited from the site's language. | | `timeZone` | `string` | No | `-` | The IANA time zone dates are evaluated in, e.g. `Europe/Berlin`. Defaults to the time zone of the browser. | | `name` | `string` | No | `-` | The `name` attribute of the underlying input. Inherited from a surrounding field when available. | | `disabled` | `boolean` | No | `-` | Whether the date picker is disabled. Inherited from a surrounding field when available. | | `readOnly` | `boolean` | No | `-` | Whether the date picker is read-only. Inherited from a surrounding field when available. | | `required` | `boolean` | No | `-` | Whether the date picker is required. Inherited from a surrounding field when available. | | `invalid` | `boolean` | No | `-` | Whether the date picker is invalid. Inherited from a surrounding field when available. | | `outsideDaySelectable` | `boolean` | No | `false` | Whether a day outside the visible month can be selected. | | `min` | `DateTimeInterface\|string` | No | `-` | The minimum date that can be selected: an ISO date string (`2025-01-31`) or a `DateTimeInterface`. | | `max` | `DateTimeInterface\|string` | No | `-` | The maximum date that can be selected: an ISO date string (`2025-01-31`) or a `DateTimeInterface`. | | `closeOnSelect` | `boolean` | No | `true` | Whether the calendar should close after the date selection is complete. Ignored when `selectionMode` is `multiple`. | | `openOnClick` | `boolean` | No | `false` | Whether to open the calendar when the input is clicked. | | `defaultValue` | `DateTimeInterface\|string\|array` | No | `-` | The initial selected date(s) when rendered: an ISO date string (`2025-01-31`), a `DateTimeInterface`, or a list of them. Use when you don't need to control the selected date(s) of the date picker. Inherited from a surrounding field when available. | | `defaultFocusedValue` | `DateTimeInterface\|string` | No | `-` | The initially focused date when rendered: an ISO date string or a `DateTimeInterface`. Use when you don't need to control the focused date of the date picker. | | `numOfMonths` | `integer` | No | `-` | The number of months the day view shows next to each other. | | `startOfWeek` | `integer` | No | `1` | The first day of the week. `0` is Sunday, `1` is Monday, and so on. | | `fixedWeeks` | `boolean` | No | `-` | Whether the calendar should render with a fixed number of weeks (6), instead of 5 or 6 depending on the month. | | `showWeekNumbers` | `boolean` | No | `-` | Whether to show the week number column in the day view. | | `selectionMode` | `Enum\DatePickerSelectionMode` | No | `Single` | The selection mode of the calendar: `single`, `multiple`, or `range`. | | `maxSelectedDates` | `integer` | No | `-` | The maximum number of dates that can be selected. Only applicable when `selectionMode` is `multiple`. | | `placeholder` | `string` | No | `-` | The placeholder text of the input. Defaults to the date format of the `locale`, e.g. `dd.mm.yyyy`. | | `defaultView` | `Enum\DatePickerView` | No | `Day` | The view the calendar starts in: `day`, `month`, or `year`. | | `minView` | `Enum\DatePickerView` | No | `Day` | The smallest view of the calendar. `month` turns it into a month picker. | | `maxView` | `Enum\DatePickerView` | No | `Year` | The largest view of the calendar. | | `positioning` | `array` | No | `{ "placement": "bottom-start", "gutter": 8 }` | The positioning options of the calendar content. | | `defaultOpen` | `boolean` | No | `false` | The initial open state of the date picker when rendered. Use when you don't need to control the open state of the date picker. | | `inline` | `boolean` | No | `false` | Whether to render the calendar in the page, without a popup. It is always open and has no trigger. | | `translations` | `array` | No | `-` | Localized date picker labels, by the id of the `datePicker.*` units of the language file. Use `f:translate` for per-template localization overrides when needed. | | `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. | | `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | | `rootId` | `string` | No | `-` | The root ID of the component, used for hydration and identification. | | `ids` | `array` | No | `[]` | The IDs of of the component parts for composition. | | `autoMount` | `boolean` | No | `true` | Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()` | | `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. | #### Rendered data attributes | Attribute | Description | | --- | --- | | `data-date-picker-root` | | | `data-state` | "open" \| "closed" | | `data-disabled` | Present when disabled | | `data-readonly` | Present when read-only | | `data-empty` | Present when the content is empty | ### datePicker.label Labels an input. Renders a `