Stimulus Datepicker

This is a Stimulus-powered datepicker which:

• localises and parses dates in the input field according to the strftime directives you configure;
• presents a calendar closely adhering to the WAI-ARIA date picker dialog design pattern;
• sends the date back to the server in ISO8601 format (YYYY-MM-DD).

Please see the demo page for a few simple examples.

Your server produces an ISO8601 date; your user interacts with it in the format you configured and/or via the popup calendar; the form sends the date back to the server in ISO format.

Month and day names are generated in the user's locale. Button titles and ARIA labels are customisable, e.g. for localisation.

Dates are local; no timezones or daylight savings are involved.

You can easily adjust the calendar's appearance via CSS custom properties or just overriding the CSS classes.

Size: JS 3.6kB minified and gzipped, CSS 2.7kB gzipped.

Installation

The project contains JavaScript and CSS. If you only use importmaps, i.e. you don't use jsbundling-rails or cssbundling-rails, first install the JavaScript:

bin/importmap pin stimulus-datepicker

And then add a link to the stylesheet to your view:

<link rel="stylesheet" href="https://unpkg.com/[email protected]/css/datepicker.css" data-turbo-track="reload">

If you use jsbundling-rails or cssbundling-rails, follow their instructions for installing packages.

Then register the datepicker controller with your Stimulus application:

  // app/javascript/controllers/application.js

  import { Application } from '@hotwired/stimulus'
+ import { Datepicker } from 'stimulus-datepicker'

  const application = Application.start()
+ application.register('datepicker', Datepicker)

Usage

To use the datepicker, wrap your input field with a controller div.

<div data-controller="datepicker">
  <input data-datepicker-target="input" type="text" name="foobar" value="2022-03-23"/>
  <span data-datepicker-target="toggle">calendar</span>
</div>

Your calendar icon or equivalent must have the data attribute data-datepicker-target="toggle".

The input field:

• must have the data attribute data-datepicker-target="input";
• should have type="text", not type="date", to avoid conflicting with built-in browser functionality;
• must have a name;
• its value, if given, must be a YYYY-MM-DD date string.

Configuration

You can configure your datepicker with the following attributes. Declare them on your controller as data-datepicker-[name]-value.

Name	Default	Description
format	"%Y-%m-%d"	Format for the date in the input field (see below).
first-day-of-week	1	First day of the week in the calendar (Sunday is 0).
day-name-length	2	Length of the abbreviated day names in the calendar, e.g. "Mo".
allow-weekends	"true"	Whether weekends are selectable.
month-jump	"dayOfMonth"	When jumping to the previous/next month, whether to go to the same day of the month ("dayOfMonth") or the same day of the week ("dayOfWeek").
min	""	The earliest choosable date (YYYY-MM-DD).
max	""	The latest choosable date (YYYY-MM-DD).
underflow-message	""	Client-side form validation message when the selected date is earlier than the min date. %s is replaced with the formatted min date. E.g. "Date must be %s or later."
overflow-message	""	Client-side form validation message when the selected date is later than the max date. %s is replaced with the formatted max date. E.g. "Date must be %s or earlier."
disallow	[]	Dates which cannot be selected. E.g. ["2022-12-25", "2023-01-01"]
text	{ underflow: "", overflow: "", previousMonth: "Previous month", nextMonth: "Next month", today: "Today", chooseDate: "Choose Date", changeDate: "Change Date" }	User-facing text. The value object is merged into the defaults. underflow: client-side form validation message when the selected date is earlier than the min date. %s is replaced with the formatted min date. E.g. "Date must be %s or later." overflow: client-side form validation message when the selected date is later than the max date. %s is replaced with the formatted max date. E.g. "Date must be %s or earlier." previousMonth, nextMonth, today: button titles and ARIA labels chooseDate, changeDate: ARIA labels
locales	["default"]	Locale for month and day names, along with fallbacks. Use BCP 47 language tags. E.g. ["de-DE", "default"].

You can use the following strftime directives in data-datepicker-format-value:

Directive	Meaning
%d	Day of the month, zero-padded (01..31)
%-d	Day of the month, no padding (1..31)
%m	Month of the year, zero-padded (01..12)
%-m	Month of the year, no padding (1..12)
%B	The full month name in the browser's locale (January)
%b	The abbreviated month name in the browser's locale (Jan)
%Y	Full year, four digits (2022)
%y	Year in 21st Century, two digits (22)

Keyboard support

The datepicker is fully navigable by keyboard. In addition to the WAI-ARIA keys, you can also use Vim-style movement keys.

Toggle target (your calendar icon)

Key	Result
Space, Enter	Open the datepicker dialog. Move focus to selected date, i.e. the date displayed in the input text field. If no date has been selected, focus on the current date.

Datepicker dialog (the calendar)

Key	Result
Escape	Close the dialog and return focus to the toggle target.
Tab	Move focus to next element in the dialog's tab sequence. The dialog "traps" focus so if focus is on the last item, move focus to the first.
Shift + Tab	Move focus to previous element in the dialog's tab sequence. The dialog "traps" focus so if focus is on the first item, move focus to the last.

Previous-month / today / next-month Buttons

Key	Result
Space, Enter	Change the month displayed in the calendar grid.

Date grid

Key	Result
Space, Enter	Select the date, close the dialog, move focus to the toggle target.
Up Arrow, k	Move focus to the same day of the previous week.
Down Arrow, j	Move focus to the same day of the next week.
Right Arrow, l	Move focus to the next day.
Left Arrow, h	Move focus to the previous day.
Home, ^, 0	Move focus to the first day of the current week.
End, $	Move focus to the last day of the current week.
Page Up, b	Change the grid of dates to the previous month and focus on the corresponding* date one month earlier.
Shift + Page Up, B	Change the grid of dates to the previous year and focus on the same date one year earlier.
Page Down, w	Change the grid of dates to the next month and focus on the corresponding* date one month later.
Shift + Page Down, W	Change the grid of dates to the next year and focus on the same date one year later.

^* The corresponding date in the adjacent month depends on data-datepicker-month-jump-value:

• "dayOfMonth": the corresponding date is the same date, e.g. 7th;
• "dayOfWeek": the corresponding date is the same day of the week, four weeks earlier/later.

CSS

You can alter the appearance of the calendar by setting these custom properties, or of course by just overriding the CSS classes.

Property	Default	Description
--sdp-selected	#005fcc	Background colour of selected date; colour of date focus ring.
--sdp-selected-invert	#ffffff	Colour of selected date.
--sdp-prev-month	#888888	Colour of dates in the previous month.
--sdp-next-month	#888888	Colour of dates in the next month.
--sdp-disabled	#1010104d	Colour of disabled dates; background color of selected date when disabled.
--sdp-disabled-invert	#ffffff	Colour of selected date when disabled.
--sdp-background	#ffffff	Background colour.
--sdp-border	#dddddd	Border colour.
--sdp-shadow	0deg 0% 50%	Box shadow colour (hsl).
--sdp-icon	#4a4a4acc	Colour of the icons, e.g. previous-month button.
--sdp-nav-button-background	#f5f5f5	Background colour of the navigation buttons.
--sdp-nav-button-background-hover	#eeeeee	Background colour on hover of the navigation buttons.
--sdp-days-of-week	#4a4a4a	Colour of the days of the week.

Intellectual Property

This package is copyright Andrew Stewart.

This package is available as open source under the terms of the MIT licence.