Date Picker | NDS - Vanilla National Design System

Date Picker Input

Text input with calendar dropdown for single date or date range selection

Built-in Features

What you get out of the box with zero configuration

Auto-initialization

Initializes automatically via the forms system when a .nds-date-input is found inside .nds-form-control. Calendar dropdown is created lazily on first click. For dynamic content, call NDS.DatePicker.reinit().

Dual Calendar System

Supports both Gregorian and Hijri (Islamic lunar) calendars. Add the nds-hijri class to the container to switch. Conversion uses an accurate API reference with browser Intl and mathematical fallbacks.

Date Range Selection

Add the dateRange class to enable start/end date selection. Visual indicators highlight the range with connected cells between start and end dates.

Flexible Year Range

Control the year dropdown range with data-year-before and data-year-after attributes on the input. Defaults work for most use cases.

Bilingual Support

Month names, weekday labels, and button text render in Arabic or English based on the page language. Add data-lang="ar" on the input to override. Supports RTL and LTR layouts with correct dropdown positioning.

Smart Positioning

Calendar dropdown automatically flips above the input when there is not enough space below. On mobile, the dropdown centers horizontally for better visibility.

Usage Guidelines

When and how to use the date picker effectively

When to Use

Date selection in forms where the user needs a calendar view to pick a date
Booking, scheduling, and event planning interfaces
Use date range mode for report filters, travel dates, or any start/end date pair
Use Hijri mode for government forms and services that require Islamic calendar dates
For simple known dates (birth date, ID expiry), a plain text input with a date mask may be simpler
Pre-populate the input with a value in DD/MM/YYYY format to set an initial date

JavaScript API


// Auto-initializes via nds-forms.js on any .nds-date-input
// No manual init needed. For dynamic content:
NDS.DatePicker.reinit();

// Format a Gregorian date as DD/MM/YYYY
NDS.DatePicker.CalendarConfig.gregorian.formatDate(new Date());

// Convert between Gregorian and Hijri
NDS.DatePicker.CalendarConfig.hijri.gregorianToHijri(new Date());
// Returns: { day, month, year }

NDS.DatePicker.CalendarConfig.hijri.hijriToGregorian(1447, 9, 1);
// Returns: Date object

// Create a Hijri date object
NDS.DatePicker.createHijriDate(1, 9, 1447);

// Read the converted date (opposite calendar) from the input
var input = document.querySelector('.nds-date-input');
var converted = input.dataset.convertedDate;

// Disable or require the date picker programmatically
NDS.Forms.setState(input, 'disabled', true);
NDS.Forms.setState(input, 'required', true);