Date Picker API | RSL Components

Quick Start

Get Started in 2 Minutes

Include the CSS and JavaScript files, add a data attribute to any input, and you're ready to go!

1. Include Required Files

<!-- CSS -->
<link rel="stylesheet" href="styles/date-picker.css">

<!-- JavaScript (at end of body) -->
<script src="javascript/date-picker.js"></script>

2. Add to Your HTML

<!-- Single Date Picker -->
<input type="text" data-rsl-date-picker placeholder="Select a date">

<!-- Date Range Picker -->
<input type="text" data-rsl-date-picker data-mode="range" placeholder="Select date range">

<!-- Multiple Dates -->
<input type="text" data-rsl-date-picker data-mode="multiple" placeholder="Select dates">

That's it! The date picker automatically initializes on page load and handles all accessibility features for you.

Key Features

Full ADA Compliance

WCAG 2.1 AA compliant with complete keyboard navigation, screen reader support, and focus management.

Three Selection Modes

Single date, date range, or multiple date selection - all from a unified, intuitive interface.

Full Keyboard Navigation

Arrow keys, Page Up/Down, Home/End, Tab, and Escape - all standard keyboard patterns supported.

Quick Presets

Built-in presets for Today, Yesterday, Last 7/30 Days, This Month, Last Month, and more.

Dark Mode Ready

Automatically adapts to your site's theme with beautiful dark mode styling.

Fully Responsive

Touch-friendly interface that works perfectly on all device sizes.

Data Attributes API

Configure the date picker entirely through HTML data attributes - no JavaScript required!

Core Attributes

Attribute	Values	Default	Description
`data-rsl-date-picker`	(presence)	—	Required. Marks the input as a date picker.
`data-mode`	`single`, `range`, `multiple`	`single`	Selection mode for the date picker.
`data-format`	Date format string	`MM/DD/YYYY`	Display format for selected dates.
`data-first-day`	`0`-`6`	`0`	First day of week (0=Sunday, 1=Monday, etc.)

Date Constraints

Attribute	Values	Default	Description
`data-min-date`	ISO date or `today`	none	Minimum selectable date.
`data-max-date`	ISO date or `today`	none	Maximum selectable date.
`data-disabled-dates`	Comma-separated ISO dates	none	Specific dates to disable.
`data-disabled-days`	Comma-separated day numbers	none	Days of week to disable (0=Sun, 6=Sat).

Display Options

Attribute	Values	Default	Description
`data-show-presets`	`true`, `false`	`true`	Show quick preset buttons panel.
`data-presets`	Comma-separated preset names	All presets	Which presets to show (see Presets section).
`data-months`	`1`, `2`	`1` (single), `2` (range)	Number of months to display at once.
`data-inline`	`true`, `false`	`false`	Display calendar inline instead of popup.
`data-auto-close`	`true`, `false`	`true`	Auto-close after selection (single mode).

Initial Value

Attribute	Values	Default	Description
`data-value`	ISO date(s)	none	Initial selected date(s). For range: `start,end`

Built-in Presets

Quick preset buttons allow users to select common date ranges with a single click.

Preset Name	Label	Description
`today`	Today	Current date
`yesterday`	Yesterday	Previous day
`last7`	Last 7 Days	Past week including today
`last30`	Last 30 Days	Past month including today
`thisMonth`	This Month	Current calendar month
`lastMonth`	Last Month	Previous calendar month
`thisYear`	This Year	Current calendar year

<!-- Show only specific presets -->
<input type="text"
       data-rsl-date-picker
       data-mode="range"
       data-presets="today,last7,last30,thisMonth">

<!-- Hide presets entirely -->
<input type="text"
       data-rsl-date-picker
       data-mode="range"
       data-show-presets="false">

JavaScript API

For advanced use cases, the Date Picker exposes a full JavaScript API.

Global Methods

Method	Parameters	Description
`RSL.DatePicker.init()`	—	Initialize all date pickers on the page. Called automatically on DOMContentLoaded.
`RSL.DatePicker.create(element, options)`	Element, config object	Create a date picker on a specific element with custom options.
`RSL.DatePicker.open(element)`	Element or selector	Programmatically open a date picker.
`RSL.DatePicker.close(element)`	Element or selector	Programmatically close a date picker.
`RSL.DatePicker.getValue(element)`	Element or selector	Get the current selected value(s) as Date object(s).
`RSL.DatePicker.setValue(element, value)`	Element, Date/array	Set the selected value programmatically.
`RSL.DatePicker.clear(element)`	Element or selector	Clear the selected value(s).
`RSL.DatePicker.destroy(element)`	Element or selector	Remove date picker and clean up event listeners.

Example Usage

// Create programmatically with custom options
RSL.DatePicker.create('#booking-date', {
    mode: 'range',
    minDate: new Date(),
    showPresets: true,
    presets: ['today', 'last7', 'last30'],
    onChange: function(dates) {
        console.log('Selected:', dates);
    }
});

// Get selected value
const value = RSL.DatePicker.getValue('#booking-date');
console.log(value); // { start: Date, end: Date }

// Set value programmatically
RSL.DatePicker.setValue('#booking-date', {
    start: new Date('2025-01-01'),
    end: new Date('2025-01-07')
});

// Listen for changes
document.querySelector('#booking-date').addEventListener('rsl-date-change', (e) => {
    console.log('Date changed:', e.detail);
});

Events

The Date Picker dispatches custom events for integration with your application.

Event	Detail Properties	Description
`rsl-date-change`	`value`, `formatted`, `mode`	Fired when the selected date(s) change.
`rsl-date-open`	—	Fired when the picker opens.
`rsl-date-close`	`value`	Fired when the picker closes.
`rsl-date-clear`	—	Fired when the selection is cleared.

FilterBus Integration

The Date Picker integrates with RSL's FilterBus for cross-component communication, allowing date selections to filter data in tables, charts, and other components.

Publish-Only Component

The Date Picker publishes date selection to FilterBus. Other components (Smart Table, Charts, KPI Cards) can subscribe to filter their data by date range.

FilterBus Attribute

Attribute	Values	Description
`data-filterbus-publish`	Filter key (string)	Publishes date selection to FilterBus with the specified key.

Published Value Structure

The published value varies by date picker mode:

// Single mode publishes:
{
    mode: 'single',
    date: '2025-12-03',           // ISO format
    formatted: '12/03/2025'       // Display format
}

// Range mode publishes:
{
    mode: 'range',
    startDate: '2025-12-01',      // ISO format
    endDate: '2025-12-31',        // ISO format
    dateRange: ['2025-12-01', '2025-12-31'],  // Convenience array
    formatted: '12/01/2025 - 12/31/2025'       // Display format
}

Usage Example

<!-- Date picker publishes to 'dateFilter' key -->
<input type="text"
       data-rsl-date-picker
       data-mode="range"
       data-show-presets="true"
       data-filterbus-publish="dateFilter">

<!-- Smart Table subscribes to date filter -->
<div data-rsl-smart-table
     data-filterbus-subscribe="dateFilter"
     data-filterbus-date-field="orderDate">
    ...
</div>

See Live Demo

View the FilterBus Demo page to see the Date Picker working with Smart Tables, Charts, and other components.

Keyboard Navigation

Full keyboard accessibility is built-in. Users can navigate the entire date picker without a mouse.

Key	Action
`Enter` / `Space`	Open picker (on input) or select focused date
`Escape`	Close picker and return focus to input
`Tab`	Move between picker sections (trapped within picker)
`←` `→`	Previous/next day
`↑` `↓`	Same day previous/next week
`Page Up`	Previous month
`Page Down`	Next month
`Home`	First day of month
`End`	Last day of month

Accessibility Features

The RSL Date Picker is designed with accessibility as a core requirement, not an afterthought.

WCAG 2.1 AA Compliant

All accessibility features are handled automatically. Developers don't need to add any ARIA attributes or keyboard handlers - they're all built in.

Built-in Accessibility

ARIA Roles: Proper role="dialog", role="grid", role="gridcell" structure
Live Regions: Screen reader announcements for month changes and selections
Focus Trapping: Focus stays within the picker when open
Focus Management: Focus moves logically and returns to input on close
Roving Tabindex: Arrow key navigation within the calendar grid
Visible Focus: Clear focus indicators on all interactive elements
Touch Targets: Minimum 44x44px touch targets for mobile accessibility
Reduced Motion: Respects prefers-reduced-motion setting
High Contrast: Supports Windows High Contrast Mode

CSS Customization

Customize the date picker appearance using CSS custom properties.

:root {
    /* Colors */
    --rsl-dp-primary: #6E7BFF;
    --rsl-dp-primary-hover: #5a66e0;
    --rsl-dp-bg: #ffffff;
    --rsl-dp-text: #1a1a2e;
    --rsl-dp-text-muted: #6b7280;
    --rsl-dp-border: #e5e7eb;

    /* Selection */
    --rsl-dp-selected-bg: #6E7BFF;
    --rsl-dp-selected-text: #ffffff;
    --rsl-dp-range-bg: rgba(110, 123, 255, 0.15);
    --rsl-dp-today-border: #6E7BFF;

    /* Disabled */
    --rsl-dp-disabled-text: #d1d5db;

    /* Focus */
    --rsl-dp-focus-ring: rgba(110, 123, 255, 0.5);

    /* Sizing */
    --rsl-dp-radius: 12px;
    --rsl-dp-day-size: 44px;
    --rsl-dp-shadow: 0 20px 40px rgba(0, 0, 0, 0.15);
}

Date Picker v1.0.0