Skip to main content

Date Picker Events

The Date & Time field includes an optional Flatpickr picker. Use the theme attribute below to control its appearance, or the Freeform JS Plugin events to customize its options and rendered calendar.

These examples apply to Freeform's built-in picker. Browser-native date inputs and date pickers initialized by your own JavaScript use their own styling and configuration.

​Dark Picker ThemeNew in 5.17.3+

Freeform's bundled Basic Dark, Bootstrap 5 Dark, Tailwind 3 Dark, Tailwind 4 Dark, and daisyUI 5 Dark formatting templates automatically use a dark picker. This covers date-only, combined date/time, and time-only pickers. Other forms keep the default light picker.

The theme styles are included in Freeform's frontend CSS. If you load Freeform assets manually, include the CSS as well as the JavaScript; freeform.loadFreeformPluginCss() loads the main stylesheet.

​Enable the Dark Picker Manually

For a custom or light formatting template, add data-freeform-theme="dark" to the form or a surrounding element. For example, wrap the rendered form in your Twig template:

<div data-freeform-theme="dark">
  {{ freeform.form('contact').render() }}
</div>

Replace contact with your form handle. The attribute selects the picker theme; style the rest of the form with your own CSS or formatting template.

In a custom formatting template, you can instead add the attribute to the existing form.renderTag() options:

{{ form.renderTag({
  attributes: {
    form: {
      'data-freeform-theme': 'dark',
    },
  },
}) }}

Merge this attribute into your existing options and keep the rest of the template's fields, buttons, and closing form tag.

The nearest data-freeform-theme attribute to the date input takes precedence. Set it to light to force a light picker, including inside a dark form. The bundled dark templates set the attribute on the form itself, so an override must be on that form or a closer wrapper around the field. Freeform checks the theme when the picker initializes and whenever it opens, allowing a site theme switcher to update the attribute at runtime.

Copies of older dark templates are also recognized through data-freeform-basic-dark, data-freeform-bootstrap-dark, data-freeform-tailwind-dark, or the combination of data-freeform-daisyui and data-theme="dark". An explicit dark or light value takes precedence over these markers.

​Customize the Dark Picker Colors

Freeform adds freeform-datepicker-dark to each dark calendar. Load your overrides after Freeform's frontend stylesheet and target that calendar directly:

.flatpickr-calendar.freeform-datepicker-dark {
  --ff-datepicker-surface: #171b24;
  --ff-datepicker-text: #edf2f7;
  --ff-datepicker-muted: #a3afbf;
  --ff-datepicker-disabled: #667085;
  --ff-datepicker-border: #475467;
  --ff-datepicker-hover: #293244;
  --ff-datepicker-accent: #93c5fd;
  --ff-datepicker-accent-text: #0b2545;
  --ff-datepicker-range: #263954;

  border-radius: 10px;
}

These variables control the calendar background, text, inactive dates, borders, hover and selected states, and date-range highlights. The time controls use the same palette. Choose colors with readable text and clear focus and selected states.

Flatpickr normally appends the calendar to body, outside the form. A selector such as .my-form .flatpickr-calendar will not reach that detached popup. Set the variables on the calendar selector above, rather than only on the form or :root.

To customize one form's pickers, use the ready event to add a class to its calendars, then include that class in your CSS selector.

​Before Initialization Event

flatpickr-before-init fires before each picker is created. Modify event.options to change its Flatpickr configuration. Register the listener before Freeform initializes the form, so it also handles pickers created after AJAX page changes.

For example, this configures the pickers belonging to a form with the handle booking:

document.addEventListener('flatpickr-before-init', (event) => {
  if (event.form.dataset.handle !== 'booking') return;

  event.options.defaultHour = 8;
  event.options.minuteIncrement = 15;
  event.options.position = 'auto center';
});

defaultHour and minuteIncrement affect pickers with a time control. Keep the date format aligned with the field's settings so Freeform can validate the submitted value. Changing picker options does not change server-side validation rules.

​On Flatpickr Instance Ready Event

flatpickr-ready fires after Freeform creates and themes the picker. Access the Flatpickr instance through event.flatpickr; event.form identifies the owning form.

For example, add a class only to calendars belonging to the booking form:

document.addEventListener('flatpickr-ready', (event) => {
  if (event.form.dataset.handle !== 'booking') return;

  const instance = event.flatpickr;
  instance.calendarContainer.classList.add('booking-datepicker');
});

To limit the color overrides above to this form, change their selector to .flatpickr-calendar.freeform-datepicker-dark.booking-datepicker. This example adds a class to the existing picker; it does not create another instance.

Register ready listeners before Freeform initializes. Listen on document for all forms and filter with event.form, as above, or attach the listener directly to one form. For more behavior options and callbacks, see the Flatpickr examples and events and hooks.

Page Feedback