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.

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.