wc-datepicker

Features

🦶 Small footprint: About 8 KB minified and gzipped.
🪁 Dependency-free: No external dependencies.
🖼 Framework-agnostic: Standard Web Component that works with any framework.
💪 Strongly typed: Written in TypeScript.
🧏‍♀️ Accessible: Built to support users of assistive technology.
🇪🇺 Localizable: Customizable labels and date formats.
🌈 Customizable: Semantic markup with no built-in styles.
🧪 Well tested: Quality assured by means of unit tests.
📆 Range selection: Allows to select single dates or ranges.

Demo

Current theme: light.css

Property	Value
`disabled` Disable the datepicker
`first-day-of-week` Configure the first week day
`range` Enable range input
`locale` BCP 47 language tag
`show-month-stepper` Enable month stepper
`show-year-stepper` Enable year stepper
`show-clear-button` Enable clear button
`show-today-button` Enable today button
`start-date` Date to show initially
`value`

Install

npm install --save wc-datepicker
# or
yarn add wc-datepicker

Usage

WC Datepicker provides a standalone datepicker that makes no assumptions about how you use it. Therefore it is up to you to connect it to an input field or display it in a popover dialog, for example.

Via script tags

Include the following script tags in your HTML.

<head>
  <script
    type="module"
    src="https://cdn.jsdelivr.net/npm/wc-datepicker/dist/esm/wc-datepicker.js"
  ></script>

  <!-- Loading the theme is optional. -->
  <link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/wc-datepicker/dist/themes/light.css"
  />
</head>

<body>
  <wc-datepicker></wc-datepicker>
</body>

Using a bundler

Import the component using a bundler like rollup.js or esbuild.

import { WcDatepicker } from "wc-datepicker/dist/components/wc-datepicker";

// Importing a theme is optional.
import "wc-datepicker/dist/themes/light.css";

customElements.define("wc-datepicker", WcDatepicker);

With a bundler and automatic lazy loading

If you are using a bundler and want to take advantage of automatic lazy loading, you can call the provided defineCustomElements function. This will only load a small entry file on page load. The component code is loaded only when the component is actually rendered.

import { defineCustomElements } from "wc-datepicker/dist/loader";

// Importing a theme is optional.
import "wc-datepicker/dist/themes/light.css";

defineCustomElements();

Options

Options with a primitive type can be passed as attributes. Non-primitive options have to be set as properties on the datepicker instance.

Example:

<wc-datepicker first-day-of-week="1" id="datepicker"></wc-datepicker>

<script>
  const datepicker = document.getElementById('datepicker');

  datepicker.disableDate = function(date) {
    // disable Sundays
    return date.getDay() === 0;
  }
</script>

Attribute / Property	Type	Default	Description
`disabled`	`boolean`	`false`	Disable the datepicker.
`disableDate`	`(date: Date) => boolean`	`() => false`	Function that gets passed each displayed date. Should return `true` to disable it.
`element-class-name`	`string`	`wc-datepicker`	Prefix for all element class names.
`first-day-of-week`	`number`	`0`	Set first day of a week. `0` for Sunday, `6` for Saturday.
`range`	`boolean`	`false`	Enable/disable range selection.
`labels`	`WCDatepickerLabels`	See below.	Set label text.
`locale`	`string`	`navigator?.language \|\| 'en-US'`	BCP 47 locale string used to format dates.
`show-clear-button`	`boolean`	`false`	Enable/disable the clear button.
`show-month-stepper`	`boolean`	`true`	Enable/disable the month stepper buttons.
`show-today-button`	`boolean`	`false`	Enable/disable the today button.
`show-year-stepper`	`boolean`	`false`	Enable/disable the year stepper buttons.
`start-date`	`string`	The current date.	Date in `YYYY-MM-DD` format used to determine the initially displayed month.
`value`	`Date \| Date[] \| undefined`		The currently selected date. Array of start and end date if range selection is enabled.
`go-to-range-start-on-select`	`boolean`	`true`	Controls whether the calendar view switches to the start of the range after the end date is selected. This only affects selections where the start and end dates are in different months.

Default labels:

{
  clearButton: 'Clear value',
  monthSelect: 'Select month',
  nextMonthButton: 'Next month',
  nextYearButton: 'Next year',
  picker: 'Choose date',
  previousMonthButton: 'Previous month',
  previousYearButton: 'Previous year',
  todayButton: 'Show today',
  yearSelect: 'Select year'
}

Events

Name	Type	Description
selectDate	`CustomEvent<string \| string[] \| undefined>`	Fired when a date is selected.
changeMonth	`CustomEvent<{ month: number; year: number; }>`	Fired when the displayed month or year changes.

Example:

<wc-datepicker id="datepicker"></wc-datepicker>

<script>
  const datepicker = document.getElementById('datepicker');

  datepicker.addEventListener('selectDate', function(event) {
    console.log(event.detail);
  });
</script>

Styling

The datepicker comes without any bundled styles. You can either load one of the included themes or write your own styles. Below is a list of all element classes you can use for styling.

Class	Element description
`.wc-datepicker`	Outer element of the datepicker
`.wc-datepicker--disabled`	Outer element of the disabled datepicker
`.wc-datepicker__header`	Element containing the stepper buttons and month/year input fields
`.wc-datepicker__previous-year-button`	Previous year stepper button
`.wc-datepicker__previous-month-button`	Previous month stepper button
`.wc-datepicker__next-year-button`	Next year stepper button
`.wc-datepicker__next-month-button`	Next month stepper button
`.wc-datepicker__current-month`	Wrapper of the month/year input fields
`.wc-datepicker__month-select`	Month select element
`.wc-datepicker__year-select`	Year text input element
`.wc-datepicker__body`	Wrapper of the calendar table
`.wc-datepicker__calendar`	Calendar table element
`.wc-datepicker__calendar-header`	Table header including the weekdays
`.wc-datepicker__weekday-row`	Table row including the weekday cells
`.wc-datepicker__weekday`	Weekday cell
`.wc-datepicker__calendar-row`	Table row including one week of dates
`.wc-datepicker__date`	Date cell
`.wc-datepicker__date--current`	Currently focused date cell
`.wc-datepicker__date--disabled`	Disabled date cell
`.wc-datepicker__date--overflowing`	Date cell of the previous or next month
`.wc-datepicker__date--today`	Date cell of the current day
`.wc-datepicker__date--selected`	Currently selected date cell
`.wc-datepicker__date--in-range`	Date cell within the currently selected range
`.wc-datepicker__date--start`	Date cell starting the selected range
`.wc-datepicker__date--end`	Date cell ending the selected range
`.wc-datepicker__footer`	Table footer containing the today and clear buttons
`.wc-datepicker__today-button`	Today button element
`.wc-datepicker__clear-button`	Clear button element

Browser support

Browser	Supported versions
Google Chrome	61+
Apple Safari	11+
Mozilla Firefox	63+
Microsoft Edge	79+

Keyboard controls

Key	Action
`Tab`	Cycle through the focusable elements.
`Space`, `Enter`	Select current day.
`Arrow left`	Move cursor to previous day.
`Arrow right`	Move cursor to next day.
`Arrow up`	Move cursor to previous week.
`Arrow down`	Move cursor to next week.
`Page up`	Move cursor to previous month.
`Page down`	Move cursor to next month.
`Shift` + `Page up`	Move cursor to previous year.
`Shift` + `Page down`	Move cursor to next year.
`Home`	Move cursor to first day of the month.
`End`	Move cursor to last day of the month.

License

Licensed under the MIT license.