Skip to content

Home

Jump to bottom
Franky Van Liedekerke edited this page Dec 12, 2025 · 20 revisions

FDatepicker Options Documentation

This document provides a comprehensive guide to all available options for FDatepicker, including both JavaScript initialization options and HTML data attributes.

Table of Contents

Basic Usage

JavaScript Initialization

const datepicker = new FDatepicker(inputElement, {
    format: 'm/d/Y',
    autoClose: true
});

HTML Data Attributes

Use data-attributes as you would options:

<input type="text" 
       data-format="m/d/Y" 
       data-auto-close="true"
       >

Configuration Options

Date Format Options

format

  • Type: string
  • Default: 'm/d/Y' (or from locale)
  • Description: The display format for dates in the input field, see Format Tokens for the complete list of supported formats.
  • Data Attribute: data-format 
// Examples
format: 'm/d/Y'      // 12/25/2023
format: 'd/m/Y'      // 25/12/2023
format: 'Y-m-d'      // 2023-12-25
format: 'F j, Y'     // December 25, 2023
format: 'm/d/Y h:i A' // 12/25/2023 2:30 PM

altFormat

  • Type: string
  • Default: 'Y-m-d'
  • Description: Format for the alternative field (usually machine-readable)
  • Data Attribute: data-alt-format

altField

  • Type: string
  • Default: null
  • Description: ID of an alternative input field to store formatted date
  • Data Attribute: data-alt-field 
<input type="text" id="display-date" data-alt-field="hidden-date">
<input type="hidden" id="hidden-date" name="date">

Date Selection Options

view

  • Type: string
  • Default: 'days'
  • Options: 'days', 'months', 'years'
  • Description: Initial view when datepicker opens
  • Data Attribute: data-view

minDate

  • Type: Date or string
  • Default: null
  • Description: Minimum selectable date
  • Data Attribute: data-min-date 
minDate: new Date(2023, 0, 1)  // January 1, 2023
// or
minDate: '2023-01-01'

maxDate

  • Type: Date or string
  • Default: null
  • Description: Maximum selectable date
  • Data Attribute: data-max-date

disabledDates

  • Type: array of strings
  • Default: []
  • Description: Array of dates to disable (in Y-m-d format)
  • Data Attribute: data-disabled-dates (comma-separated)
disabledDates: ['2023-12-25', '2023-12-31']
<input data-disabled-dates="2023-12-25,2023-12-31">

disabledDays

  • Type: array of integers
  • Default: []
  • Description: Array of days of the week to disable (0=Sunday, 6=Saturday)
  • Data Attribute: data-disabled-days (comma-separated)

Example to disable all weekends:

disabledDays: [0, 6] 
<input data-disabled-days="0,6">

Range Selection Options

range

  • Type: boolean
  • Default: false
  • Description: Enable date range selection
  • Data Attribute: data-range 
<input type="text" data-range="true">

Multiple Selection Options

multiple

  • Type: boolean
  • Default: false
  • Description: Enable multiple date selection
  • Data Attribute: data-multiple

multipleSeparator

  • Type: string
  • Default: ','
  • Description: Separator for multiple dates in input field
  • Data Attribute: data-multiple-separator

altFieldMultipleSeparator

  • Type: string
  • Default: ','
  • Description: Separator for multiple dates in alternative field
  • Data Attribute: data-alt-field-multiple-separator

multipleDisplaySelector

  • Type: string
  • Default: empty
  • Description: CSS selector for element to display selected dates info
  • Data Attribute: data-multiple-display-selector 
<input type="text" data-multiple="true" data-multiple-display-selector="#selected-info">
<div id="selected-info"></div>

Time Picker Options

timepicker

  • Type: boolean
  • Default: false
  • Description: Enable time selection
  • Data Attribute: data-timepicker

timeOnly

  • Type: boolean
  • Default: false
  • Description: Enable only time selection, no datepicker
  • Data Attribute: data-time-only

ampm

  • Type: boolean
  • Default: Auto-detected from format, or false
  • Description: Use 12-hour format with AM/PM
  • Data Attribute: data-ampm 
// 24-hour format
timepicker: true,
ampm: false

// 12-hour format
timepicker: true,
ampm: true

timepickerDefaultNow

  • Type: boolean
  • Default: true
  • Description: Default time picker to current time
  • Data Attribute: data-timepicker-default-now

hoursStep

  • Type: integer
  • Default: 1
  • Description: Step interval for hours input (e.g., 2 = every 2 hours)
  • Data Attribute: data-hours-step

minutesStep

  • Type: integer
  • Default: 1
  • Description: Step interval for minutes input (e.g., 15 = every 15 minutes)
  • Data Attribute: data-minutes-step

minHours

  • Type: integer
  • Default: 0 (24-hour) or 1 (12-hour)
  • Description: Minimum selectable hour
  • Data Attribute: data-min-hours

maxHours

  • Type: integer
  • Default: 23 (24-hour) or 12 (12-hour)
  • Description: Maximum selectable hour
  • Data Attribute: data-max-hours

minMinutes

  • Type: integer
  • Default: 0
  • Description: Minimum selectable minutes
  • Data Attribute: data-min-minutes

maxMinutes

  • Type: integer
  • Default: 59
  • Description: Maximum selectable minutes
  • Data Attribute: data-max-minutes

UI Behavior Options

autoClose

  • Type: boolean
  • Default: true
  • Description: Close datepicker after date selection
  • Data Attribute: data-auto-close

firstDayOfWeek

  • Type: integer
  • Default: taken from locale, or 1 if not set anywhere (Monday)
  • Options: 0 (Sunday) through 6 (Saturday)
  • Description: First day of the week
  • Data Attribute: data-first-day-of-week 
firstDayOfWeek: 1  // Monday
firstDayOfWeek: 0  // Sunday

weekendDays

  • Type: array of strings
  • Default: [0,6]
  • Description: Array of dates considered as weekend days (0=Sunday, 6=Saturday)
  • Data Attribute: data-weekend-days (comma-separated)
weekendDays: [5,6]
<input data-weekend-days="5,6">

todayButton

  • Type: boolean
  • Default: true
  • Description: Show "Today" button
  • Data Attribute: data-today-button

clearButton

  • Type: boolean
  • Default: true
  • Description: Show "Clear" button
  • Data Attribute: data-clear-button

closeButton

  • Type: boolean
  • Default: true
  • Description: Show "Close" button
  • Data Attribute: data-close-button

Hooks

onOpen

onClose

onSelect

Localization Options

Pre-built Language Files

FDatepicker comes with pre-built language files in the src/js/i18n/ directory. Simply include one of these files after the main FDatepicker script to automatically activate that language:

Available Languages:

  • fdatepicker.ar.js - Arabic
  • fdatepicker.cs.js - Czech
  • fdatepicker.da.js - Danish
  • fdatepicker.de.js - German
  • fdatepicker.el.js - Greek
  • fdatepicker.en.js - English (default)
  • fdatepicker.es.js - Spanish
  • fdatepicker.fi.js - Finnish
  • fdatepicker.fr.js - French
  • fdatepicker.hu.js - Hungarian
  • fdatepicker.hy.js - Armenian
  • fdatepicker.it.js - Italian
  • fdatepicker.ka.js - Georgian
  • fdatepicker.ko.js - Korean
  • fdatepicker.nl.js - Dutch
  • fdatepicker.nl-BE.js - Dutch (Belgium)
  • fdatepicker.pl.js - Polish
  • fdatepicker.pt.js - Portuguese
  • fdatepicker.pt-BR.js - Portuguese (Brazil)
  • fdatepicker.ro.js - Romanian
  • fdatepicker.ru.js - Russian
  • fdatepicker.si.js - Slovenian
  • fdatepicker.sk.js - Slovak
  • fdatepicker.sv.js - Swedish
  • fdatepicker.th.js - Thai
  • fdatepicker.tr.js - Turkish
  • fdatepicker.uk.js - Ukrainian
  • fdatepicker.zh.js - Chinese

Usage:

<script src="path/to/fdatepicker.js"></script>
<script src="path/to/src/js/i18n/fdatepicker.fr.js"></script>
<!-- All datepickers will now use French localization -->

Custom Localization

Use FDatepicker.setMessages() to create custom localization or override specific messages:

FDatepicker.setMessages({
    days: ['Dimanche', 'Lundi', 'Mardi', 'Mercredi', 'Jeudi', 'Vendredi', 'Samedi'],
    daysShort: ['Dim', 'Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam'],
    daysMin: ['Di', 'Lu', 'Ma', 'Me', 'Je', 'Ve', 'Sa'],
    months: ['Janvier', 'Février', 'Mars', 'Avril', 'Mai', 'Juin', 
             'Juillet', 'Août', 'Septembre', 'Octobre', 'Novembre', 'Décembre'],
    monthsShort: ['Jan', 'Fév', 'Mar', 'Avr', 'Mai', 'Jun', 
                  'Jul', 'Aoû', 'Sep', 'Oct', 'Nov', 'Déc'],
    today: 'Aujourd\'hui',
    clear: 'Effacer',
    close: 'Fermer',
    format: 'd/m/Y',
    firstDayOfWeek: 1,
    noDatesSelected: 'Aucune date sélectionnée',
    datesSelected: 'Dates sélectionnées ({0}):'
});

Data Attributes

All options can be set via HTML data attributes. The datepicker automatically reads these when initializing:

<input type="text" 
       data-format="m/d/Y h:i A"
       data-timepicker="true"
       data-ampm="true"
       data-auto-close="false"
       data-min-date="2023-01-01"
       data-max-date="2023-12-31"
       data-disabled-dates="2023-12-25,2023-01-01"
       data-first-day-of-week="1"
       data-today-button="true"
       data-clear-button="true"
       data-close-button="true"
       data-hours-step="1"
       data-minutes-step="15"
       data-min-hours="8"
       data-max-hours="18"
       data-fdatepicker>

Methods

Static Methods

FDatepicker.setMessages(customMessages)

Set custom localization messages globally.

FDatepicker.destroyAll()

Destroy all datepicker instances.

FDatepicker.formatDate(date, format, locale)

Format a date with the specified format. The locale parameter is optional and defaults to the currently loaded language configuration set via FDatepicker.setMessages().

Instance Methods

open()

Open the datepicker popup.

close()

Close the datepicker popup.

toggle()

Toggle the datepicker popup.

destroy(), FDatepicker.destroyAll() and FDatepicker.cleanup()

Destroy the datepicker instance and clean up. Next to that, you can use FDatepicker.destroyAll() to destroy all instances or FDatepicker.cleanup() to clean up lingering instances

update()

Change options of an existing picker. Example:

const input = document.getElementById('localized-rec-start-date');

// Update option
input._fdatepicker.update('multiple', true);

// Or upate multiple
picker.update({ multiple: true, todayButton: true });

setDate()

Set the date of the datepicker. Expects a date object or an array of date objects as argument

const newdate = new Date();
picker.setDate(newdate);

This function takes an optional second argument that can influence the onSelect-function: by default the onSelect is also executed when calling setDater, setting the second argument to 'false' will prevent the execution of the onSelect function (if present).

Format Tokens

FDatepicker supports about the same format PHP does for date/times, which makes it very easy to use.

Token Description Example
d Day with leading zero 01, 15, 31
j Day without leading zero 1, 15, 31
l Full day name Sunday, Monday
D Short day name Sun, Mon
S Ordinal suffix st, nd, rd, th
m Month with leading zero 01, 12
n Month without leading zero 1, 12
F Full month name January, December
M Short month name Jan, Dec
Y 4-digit year 2023
y 2-digit year 23
H Hour 24-format with leading zero 00, 23
G Hour 24-format without leading zero 0, 23
i Minutes with leading zero 00, 59
s Seconds with leading zero 00, 59
A Uppercase AM/PM AM, PM
a Lowercase am/pm am, pm

Examples

HTML Data Attribute Examples

Basic Date Picker

<input type="text" data-fdatepicker>

Date Range Picker

<input type="text" data-range="true" data-format="m/d/Y">

Multiple Date Selection

<input type="text" data-multiple="true">
<div class="selected-dates-display"></div>

Date and Time Picker with Constraints

<input type="text" 
       data-timepicker="true" 
       data-format="m/d/Y h:i A"
       data-hours-step="1"
       data-minutes-step="15"
       data-min-hours="9"
       data-max-hours="5"
       data-min-minutes="0"
       data-max-minutes="45">

Localized Date Picker (Monday first)

<input type="text" 
       data-first-day-of-week="1" 
       data-format="d/m/Y">

With Min/Max Dates

<input type="text" 
       data-min-date="2023-01-01" 
       data-max-date="2023-12-31">

With Alternative Field

<input type="text" id="display" data-alt-field="hidden">
<input type="hidden" id="hidden" name="date">

JavaScript Initialization Examples

Basic Setup

// Simple datepicker
const picker = new FDatepicker(document.getElementById('date-input'));

// With custom format
const picker = new FDatepicker(document.getElementById('date-input'), {
    format: 'd/m/Y'
});

Advanced Configuration

const picker = new FDatepicker(document.getElementById('date-input'), {
    format: 'F j, Y',
    minDate: new Date(2023, 0, 1),
    maxDate: new Date(2024, 11, 31),
    disabledDates: ['2023-12-25', '2023-12-26'],
    autoClose: false,
    firstDayOfWeek: 1
});

Date Range Picker

const rangePicker = new FDatepicker(document.getElementById('range-input'), {
    range: true,
    format: 'm/d/Y',
    autoClose: true
});

Multiple Date Selection

const multiPicker = new FDatepicker(document.getElementById('multi-input'), {
    multiple: true,
    format: 'd/m/Y',
    multipleSeparator: ' | ',
    multipleDisplaySelector: '#selected-dates-info'
});

Time Picker Examples

// 24-hour time picker
const timePicker24 = new FDatepicker(document.getElementById('datetime-input'), {
    timepicker: true,
    ampm: false,
    format: 'Y-m-d H:i'
});

// 12-hour time picker
const timePicker12 = new FDatepicker(document.getElementById('datetime-input'), {
    timepicker: true,
    ampm: true,
    format: 'm/d/Y h:i A',
    timepickerDefaultNow: false
});

// Time picker with constraints and steps
const constrainedTimePicker = new FDatepicker(document.getElementById('business-hours'), {
    timepicker: true,
    ampm: false,
    format: 'Y-m-d H:i',
    hoursStep: 1,
    minutesStep: 15,        // 15-minute intervals
    minHours: 9,           // 9 AM earliest
    maxHours: 17,          // 5 PM latest
    minMinutes: 0,
    maxMinutes: 45         // No appointments after :45
});

// 12-hour format with business hour constraints
const businessHours12 = new FDatepicker(document.getElementById('appointment-time'), {
    timepicker: true,
    ampm: true,
    format: 'm/d/Y h:i A',
    hoursStep: 1,
    minutesStep: 30,       // 30-minute intervals
    minHours: 9,           // 9 AM earliest (in 12-hour this is 9)
    maxHours: 5,           // 5 PM latest (in 12-hour this is 5)
    minMinutes: 0,
    maxMinutes: 30
});

Working with Alternative Fields

const picker = new FDatepicker(document.getElementById('display-field'), {
    format: 'F j, Y',           // Human-readable format
    altField: 'hidden-field',   // Hidden field ID
    altFormat: 'Y-m-d'          // Database-friendly format
});

Event Handling

const picker = new FDatepicker(document.getElementById('date-input'), {
    format: 'm/d/Y'
});

// Listen for changes
document.getElementById('date-input').addEventListener('change', function(e) {
    console.log('Date changed to:', e.target.value);
});

// Programmatic control
document.getElementById('open-btn').addEventListener('click', (e) => {
    e.preventDefault();
    e.stopPropagation(); // needed
    picker.open();
});

// the next is not really needed, since any click outside a datepicker will close the datepicker
document.getElementById('close-btn').addEventListener('click', () => {
    picker.close();
});

Localization Setup

// Set up French localization
FDatepicker.setMessages({
    days: ['Dimanche', 'Lundi', 'Mardi', 'Mercredi', 'Jeudi', 'Vendredi', 'Samedi'],
    daysShort: ['Dim', 'Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam'],
    daysMin: ['Di', 'Lu', 'Ma', 'Me', 'Je', 'Ve', 'Sa'],
    months: ['Janvier', 'Février', 'Mars', 'Avril', 'Mai', 'Juin', 
             'Juillet', 'Août', 'Septembre', 'Octobre', 'Novembre', 'Décembre'],
    monthsShort: ['Jan', 'Fév', 'Mar', 'Avr', 'Mai', 'Jun', 
                  'Jul', 'Aoû', 'Sep', 'Oct', 'Nov', 'Déc'],
    today: 'Aujourd\'hui',
    clear: 'Effacer',
    close: 'Fermer',
    format: 'd/m/Y',
    firstDayOfWeek: 1,
    noDatesSelected: 'Aucune date sélectionnée',
    datesSelected: 'Dates sélectionnées ({0}):'
});

// Now create datepicker with French locale
const frenchPicker = new FDatepicker(document.getElementById('date-input'), {
    firstDayOfWeek: 1  // Monday first
});

Using Static formatDate Method

// Format dates without creating a datepicker instance
const date = new Date(2023, 11, 25);

// Uses currently loaded locale
const formatted = FDatepicker.formatDate(date, 'F j, Y');
console.log(formatted); // "December 25, 2023"

// Different formats
console.log(FDatepicker.formatDate(date, 'm/d/Y'));     // "12/25/2023"
console.log(FDatepicker.formatDate(date, 'Y-m-d'));     // "2023-12-25"
console.log(FDatepicker.formatDate(date, 'd/m/Y H:i')); // "25/12/2023 00:00"

Dynamic Options Update

const picker = new FDatepicker(document.getElementById('date-input'), {
    format: 'm/d/Y'
});

// You can access and modify options after initialization
// Note: Some changes may require re-rendering
picker.options.format = 'd/m/Y';
picker.options.firstDayOfWeek = 1;
picker.render(); // Re-render with new options

Cleanup and Destruction

// Destroy single instance
const picker = new FDatepicker(document.getElementById('date-input'));
picker.destroy();

// Destroy all instances (useful for SPA cleanup)
FDatepicker.destroyAll();

Complete Real-World Example

// Complete booking system date picker
const bookingPicker = new FDatepicker(document.getElementById('booking-date'), {
    format: 'F j, Y',
    minDate: new Date(), // Today
    maxDate: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000), // 90 days from now
    disabledDates: ['2024-01-01', '2024-12-25'], // Holidays
    firstDayOfWeek: 1, // Monday first
    autoClose: true,
    altField: 'booking-date-iso',
    altFormat: 'Y-m-d',
    todayButton: true,
    clearButton: true
});

// Add validation
document.getElementById('booking-date').addEventListener('change', function(e) {
    //const selectedDate = new Date(document.getElementById('booking-date-iso').value);
    const selectedDate = bookingPicker._fdatepicker.selectedDate;
    const dayOfWeek = selectedDate.getDay();
    
    if (dayOfWeek === 0 || dayOfWeek === 6) {
        alert('Sorry, bookings are only available on weekdays.');
        this.value = '';
        document.getElementById('booking-date-iso').value = '';
    }
});

Setting Global Defaults for All Datepickers

You can set default options that will be applied to all future datepicker instances by modifying the FDATEPICKER_DEFAULT_MESSAGES object or creating a wrapper function:

Method 1: Modify Global Messages (affects format and firstDayOfWeek)

// Set global defaults via messages
FDatepicker.setMessages({
    format: 'd/m/Y',
    firstDayOfWeek: 1
});

// All new datepickers will use these defaults
const picker1 = new FDatepicker(document.getElementById('date1'));
const picker2 = new FDatepicker(document.getElementById('date2'));

Method 2: Create a Configuration Template

// Define your standard configuration
const STANDARD_CONFIG = {
    format: 'd/m/Y',
    firstDayOfWeek: 1,
    autoClose: true,
    todayButton: true,
    clearButton: true,
    closeButton: false
};

// Function to create datepickers with standard config
function createStandardDatepicker(element, customOptions = {}) {
    return new FDatepicker(element, {
        ...STANDARD_CONFIG,
        ...customOptions  // Custom options override standard ones
    });
}

// Usage
const picker1 = createStandardDatepicker(document.getElementById('date1'));
const picker2 = createStandardDatepicker(document.getElementById('date2'), {
    timepicker: true  // Add timepicker to this specific instance
});

Method 3: Extend the FDatepicker Class

// Create a custom datepicker class with your defaults
class MyDatepicker extends FDatepicker {
    constructor(input, options = {}) {
        const defaultOptions = {
            format: 'd/m/Y',
            firstDayOfWeek: 1,
            autoClose: true,
            todayButton: true,
            clearButton: true,
            closeButton: false
        };
        
        super(input, { ...defaultOptions, ...options });
    }
}

// Use your custom class
const picker1 = new MyDatepicker(document.getElementById('date1'));
const picker2 = new MyDatepicker(document.getElementById('date2'), {
    range: true  // Override with range selection
});

Method 4: Batch Initialization with Shared Config

// Initialize multiple datepickers with same config
const sharedConfig = {
    format: 'F j, Y',
    firstDayOfWeek: 1,
    autoClose: true
};

const dateInputs = document.querySelectorAll('[data-shared-datepicker]');
const pickers = Array.from(dateInputs).map(input => {
    // Merge shared config with any data attributes
    return new FDatepicker(input, sharedConfig);
});

Pre-filling Dates

You can pre-fill the datepicker with dates using data attributes:

Single Date

<input type="text" data-date="2023-12-25" data-fdatepicker>

Multiple Dates

<input type="text" 
       data-date="2023-12-25,2023-12-26,2023-12-27" 
       data-multiple="true" 
       data-fdatepicker>

The format is yyyy-mm-dd for dates alone, or yyyy-mm-ddThh:mm:ss for a full datetime field. See Javascript Date time string format for more info.

Keyboard Navigation

FDatepicker includes full keyboard accessibility:

  • Arrow Keys: Navigate between dates
  • Page Up/Down: Navigate months (Shift+Page Up/Down for years)
  • Home/End: Go to first/last day of month
  • Enter/Space: Select date
  • Escape: Close datepicker
  • Tab: Navigate between UI elements

CSS Classes

The datepicker adds various CSS classes for styling:

  • .fdatepicker-popup: Main popup container
  • .fdatepicker-day: Individual day cells
  • .fdatepicker-day.selected: Selected date
  • .fdatepicker-day.today: Today's date
  • .fdatepicker-day.disabled: Disabled date
  • .fdatepicker-day.weekend: Weekend days
  • .fdatepicker-day.in-range: Dates within selected range
  • .fdatepicker-day.range-start: Start of range
  • .fdatepicker-day.range-end: End of range
  • .fdatepicker-day.multi-selected: Selected dates in multiple mode

Clone this wiki locally