A Date picker library designed and developed to be used within GOV.UK projects. Full support for 'keyboard only' users. Supports both English and Welsh.
npm i kainos-govuk-datepicker
Files & locations:
| File | Folder | Description |
|---|---|---|
| datepicker.min.js | node_modules/kainos-govuk-datepicker/dist | production build - (ES5, 14kb) |
| datepicker.min.css | node_modules/kainos-govuk-datepicker/dist | production stylesheet |
| datepicker.scss | node_modules/kainos-govuk-datepicker/src/scss | SCSS file for use in builds |
Importing the library if you're using it in Node:
import datePicker from 'kainos-govuk-datepicker';
// or
const datePicker = require('kainos-govuk-datepicker');Add a class of .date-picker (can be named differently) to your HTML form wrapper.
Ensure day, month and year inputs have a class of .date-picker-day, .date-picker-month, .date-picker-year.
See recommended HTML -
<div class="govuk-form-group">
<fieldset class="govuk-fieldset" role="group" aria-describedby="passport-issued-hint">
<legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
<h1 class="govuk-fieldset__heading">When was your passport issued?</h1>
</legend>
<div class="govuk-hint">For example, 27 3 2007</div>
<div class="govuk-date-input date-picker" id="passport-issued">
<div class="govuk-date-input__item">
<div class="govuk-form-group">
<label class="govuk-label govuk-date-input__label" for="passport-issued-day">Day</label>
<input class="govuk-input govuk-date-input__input govuk-input--width-2 date-picker-day" id="passport-issued-day" name="passport-issued-day" type="text" pattern="[0-9]*" inputmode="numeric" />
</div>
<div>
<div class="govuk-date-input__item">
<div class="govuk-form-group">
<label class="govuk-label govuk-date-input__label" for="passport-issued-month">Month</label>
<input class="govuk-input govuk-date-input__input govuk-input--width-2 date-picker-month" id="passport-issued-month" name="passport-issued-month" type="text" pattern="[0-9]*" inputmode="numeric" />
</div>
</div>
<div class="govuk-date-input__item">
<div class="govuk-form-group">
<label class="govuk-label govuk-date-input__label" for="passport-issued-year">year</label>
<input class="govuk-input govuk-date-input__input govuk-input--width-4 date-picker-year" id="passport-issued-year" name="passport-issued-year" type="text" pattern="[0-9]*" inputmode="numeric" />
</div>
</div>
</div>
</fieldset>
</div>Importing the styles into your project using Node:
// Import datepickers scss file.
@import '~kainos-govuk-datepicker/src/scss/datepicker.scss';
// Import datepickers css file.
@import '~kainos-govuk-datepicker/dist/datepicker.min.css';Using it in your code:
datePicker(selector, options, callbacks);datePicker takes 2 arguments:
selector- DOM node, such asdocument.querySelector('#my-id').options- (optional) - A configuration object (see below).callbacks- (optional) - An object of callbacks (see below)
The date picker currently supports the following configuration options:
Type: String | en or cy
Supports English en and Welsh cy. Defaults to English if not specified.
Using it in your code:
datePicker(selector, {
language: 'en', // 'cy'
});Type: Date
The minimum date the user can select. Null by default.
Using it in your code:
datePicker(selector, {
minDate: new Date(),
});Type: Date
The maximum date the user can select. Null by default.
Using it in your code:
datePicker(selector, {
maxDate: new Date(),
});Type: String
The class to append to the date picker container to assist with CSS overwrites. Empty by default.
Using it in your code:
datePicker(selector, {
theme: 'my-class-name',
});Type: String
The icon you wish to use in place of the default 'choose date' text. Please note this feature is experimental and is not fully supported in Internet Explorer.
Using it in your code:
datePicker(selector, {
icon: 'http://my-icon-url.com',
});Type: boolean
Can be set to true to let the window scroll automatically to show the calendar in full when opened. False by default.
Using it in your code:
datePicker(selector, {
autoScroll: true,
});The datepicker currently supports the following optional callbacks
A callback that accepts 3 inputs: day, month, year which are taken from the input elements.
You can then manipulate these inputs and return an object with the following structure:
{
day,
month,
year
}This returned object is then validated and used to set the focused date upon opening the date picker.
Using it in your code:
datePicker(selector, options, {
onParseInputs: function(day, month, year) {
// some minpulation logic
var manipulatedDay, manipulatedMonth, manipulatedYear;
return {
day: manipulatedDay,
month: manipulatedMonth,
year: manipulatedYear,
};
}
});A callback that accepts a Date object when a date is selected via the date picker.
Using it in your code:
datePicker(selector, options, {
onDateSelect: function(selectedDate) {
// do something with selected date
}
});Clone this repository to your local machine and install dependencies.
npm installWebpack is used to bundle the date picker's files, while express is used to spin up the local dev environment.
Both can be ran simultaneously via running -
npm run start:devAfter a few moments, you should be able to see the express server on port 8080.
The date picker component is tested via Jest unit tests and Codecept e2e tests.
To run the unit tests run -
npm run testTo run the e2e tests run -
npm run test:e2eThe CI workflows for this project currently depend upon a v1 package lockfile. When generating a new package-lock.json ensure you generate a v1 lockfile -
npm install --lockfile-version 1