FormWidgets / Date & Time / DatePicker

DatePicker

fw-datepicker

A calendar popup widget for selecting single dates. Supports custom display formats, date range constraints, weekend and holiday exclusions, and full keyboard navigation.

View Examples

Usage

HTML (Auto-init)

Add the fw-datepicker class to any text input. Call FormWidgets.autoInit() after the page loads.

HTML
<input type="text" class="fw-datepicker" id="myDate">

<script>
  FormWidgets.autoInit();
</script>

HTML with Data Attributes

Configure options directly in HTML using data-* attributes.

HTML
<input type="text" class="fw-datepicker"
       data-display-format="DD/MM/YYYY"
       data-min-date="2025-01-01"
       data-max-date="2025-12-31"
       data-exclude-weekends="true"
       data-show-pattern="true">

JavaScript Initialization

Use FormWidgets.init() for full programmatic control.

JavaScript
FormWidgets.init('#myDate', 'DatePicker', {
    displayFormat: 'DD/MM/YYYY',
    minDate: '2025-01-01',
    maxDate: '2025-12-31',
    excludeWeekends: true,
    showPattern: true
});

Options

Option Type Default Description
format string 'YYYY-MM-DD' Internal storage format. The value stored in the input element uses this format.
displayFormat string 'YYYY-MM-DD' Display format shown to the user. Supports DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD and similar patterns.
minDate string / Date null Minimum selectable date. Dates before this will be disabled in the calendar. Accepts ISO string or Date object.
maxDate string / Date null Maximum selectable date. Dates after this will be disabled in the calendar.
excludeWeekends boolean false When true, Saturdays and Sundays are disabled and cannot be selected.
excludeDates array [] Array of specific dates to disable in ISO format. Example: ['2025-12-25', '2026-01-01']
excludeDaysOfWeek array [] Array of day numbers to disable. 0 = Sunday, 1 = Monday … 6 = Saturday. Example: [0, 6] disables weekends.
showPattern boolean true When true, the expected date format is shown as a placeholder when the field is empty (e.g. DD/MM/YYYY).
icon string 'calendar' Name of the SVG icon to use from the internal icon set.
required boolean false When true, the field is treated as required and will show a validation error when empty.

Data Attributes

All options can be set via HTML data attributes. camelCase options map to kebab-case attributes.

Data AttributeEquivalent OptionExample
data-display-formatdisplayFormatdata-display-format="DD/MM/YYYY"
data-min-dateminDatedata-min-date="2025-01-01"
data-max-datemaxDatedata-max-date="2025-12-31"
data-exclude-weekendsexcludeWeekendsdata-exclude-weekends="true"
data-exclude-datesexcludeDatesdata-exclude-dates='["2025-12-25"]'
data-exclude-days-of-weekexcludeDaysOfWeekdata-exclude-days-of-week="[0,6]"
data-show-patternshowPatterndata-show-pattern="true"
data-iconicondata-icon="calendar"
data-requiredrequireddata-required="true"

Getting Values

JavaScript
// Get the value directly from the input element
const value = document.getElementById('myDate').value;
// Returns the date in the configured displayFormat, e.g. '25/12/2025'

// Get the widget instance for advanced control
const widget = FormWidgets.instances.get(document.getElementById('myDate'));

// Validate programmatically
const isValid = widget.validate();

// Clear the field
widget.clear();

Keyboard Navigation

Enter / ↓Open the calendar popup
EscClose the calendar and return focus to the input
← →Navigate by day (in calendar)
↑ ↓Navigate by week (7 days) in calendar
EnterSelect the focused date and close the calendar
TabNavigate through month dropdown, year dropdown, calendar grid, and action buttons
Shift+TabNavigate backwards through calendar controls

Manual Input

Users can also type dates directly into the field. The widget will validate and format the input on blur.

Features

Calendar Popup

Month/year navigation with an interactive calendar grid.

Manual Input

Type dates directly — the widget validates and formats on blur.

Date Exclusions

Disable weekends, specific dates, or any days of the week.

Min / Max Range

Restrict the selectable range to a defined window.

Custom Formats

DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD and more.

Smart Positioning

Calendar automatically positions above or below the input to stay on screen.

Notes

Browser Native Picker Override

If you use type="date" on your input, FormWidgets automatically converts it to type="text" to prevent the browser's native date picker from appearing.

Combining Exclusions

You can combine excludeWeekends, excludeDates, and excludeDaysOfWeek together. A date is excluded if any of these conditions match.

Pattern Placeholder

When showPattern: true (the default), the input displays its expected format as a placeholder, e.g. DD/MM/YYYY. Set showPattern: false to disable this.