An official website of the United States Government
Overview
Choose a valid formatted date.
This extends the Text Input or the Form Fields component with the ability to select a valid date from a Calendar view.
Example 05/14/1975
Variants and Examples
The Date Picker can be used with either a basic Text Input component or the Form Fields component. To instantiate an instance of the Date Picker, you pass in the Input element’s ID and select a display format. The Date display format options are listed below under Date Formatting Options.
Basic JavaScript Initialization
<div class="fsa-field">
<label class="fsa-field__label" for="date-picker-basic">Start Date</label>
<input placeholder="mm/dd/yyyy" class="fsa-input fsa-field__item" id="date-picker-basic" aria-describedby="date-picker-basic__help" aria-required="true" name="date-picker-basic" type="text" value="">
<span class="fsa-field__help" id="date-picker-basic__help">Example 05/14/1975</span>
</div>
<!-- Placed at bottom of page -->
<script>
datePickerController.createDatePicker({
// Associate the text input to a DD/MM/YYYY date format
formElements: { "date-picker-basic": "%m/%d/%Y" }
});
</script>
Fill Example
Example 05/14/1975
<div class="fsa-field fsa-field--fill">
<label class="fsa-field__label" for="date-picker-block">Start Date</label>
<input placeholder="mm/dd/yyyy" class="fsa-input fsa-field__item" id="date-picker-block" aria-describedby="date-picker-block__help" aria-required="true" name="date-picker-block" type="text" value="">
<span class="fsa-field__help" id="date-picker-block__help">Example 05/14/1975</span>
</div>
<!-- Placed at bottom of page -->
<script>
datePickerController.createDatePicker({
// Associate the text input to a DD/MM/YYYY date format
formElements: { "date-picker-block": "%m/%d/%Y" }
});
</script>
Disabled Example
Example 05/14/1975
<div class="fsa-field">
<label class="fsa-field__label" for="date-picker-disabled">Start Date</label>
<input placeholder="mm/dd/yyyy" disabled class="fsa-input fsa-field__item" id="date-picker-disabled" aria-describedby="date-picker-disabled__help" aria-required="true" name="date-picker-disabled" type="text" value="">
<span class="fsa-field__help" id="date-picker-disabled__help">Example 05/14/1975</span>
</div>
<!-- Placed at bottom of page -->
<script>
datePickerController.createDatePicker({
// Associate the text input to a DD/MM/YYYY date format
formElements: { "date-picker-disabled": "%m/%d/%Y" },
staticPos: true
});
</script>
Disable Weekends
You can only allow for the selection of specific weekdays on the calendar, by assigning an array [0,0,0,0,0,1,1] as the disabledDays property when instantiating an instance of the Date Picker. The first spot in the array represents Monday. You can also disable a specific day of the week by adding a 1 to the array for any of the days represented.
Example 07/04/2019
<div class="fsa-field">
<label class="fsa-field__label" for="date-picker-disabledweekends">Select Date</label>
<input placeholder="mm/dd/yyyy" class="fsa-input fsa-field__item" id="date-picker-disabledweekends" aria-describedby="date-picker-disabledweekends__help" aria-required="true" name="date-picker-disabledweekends" type="text" value="">
<span class="fsa-field__help" id="date-picker-disabledweekends__help">Example 07/04/2019</span>
</div>
<!-- Placed at bottom of page -->
<script>
datePickerController.createDatePicker({
formElements: { "date-picker-disabledweekends": "%m/%d/%Y" },
disabledDays:[0,0,0,0,0,1,1]
});
</script>
Upper and Lower Dates
Additional JavaScript methods can be used to limit the selection of a date. If you would like to limit the selection of a date to after a period of time, you can us the JavaScript method setRangeLow. To limit the selection of a date prior to a period of time, you use the setRangeHigh JavaScript Method. Both require you to pass in a string for the date in the YYYYDDMM format or pass in a new Date object (i.e. new Date()). The example below uses both JavaScript methods to only allow for the selection between April 7th, 2019 and Today.
Example 06/06/2019
<div class="fsa-field">
<label class="fsa-field__label" for="date-picker-upper-lower">Select Date Between 04/07/2019 - Today</label>
<input placeholder="mm/dd/yyyy" class="fsa-input fsa-field__item" id="date-picker-upper-lower" aria-describedby="date-picker-upper-lower__help" aria-required="true" name="date-picker-upper-lower" type="text" value="">
<span class="fsa-field__help" id="date-picker-upper-lower__help">Example 06/06/2019</span>
</div>
<!-- Placed at bottom of page -->
<script>
datePickerController.createDatePicker({
formElements: { "date-picker-upper-lower": "%m/%d/%Y" },
});
// disabled PRIOR to April 7, 2019
datePickerController.setRangeLow("date-picker-upper-lower", '20190407');
// disabled AFTER today
datePickerController.setRangeHigh("date-picker-upper-lower", new Date());
</script>
Static Calendar Location
By utilising the staticPos property and setting the value to true, you can have a static Calendar component displayed on the page.
Example 05/14/1975
<div class="fsa-field">
<label class="fsa-field__label" for="date-picker-static-display">Select Date</label>
<input placeholder="mm/dd/yyyy" class="fsa-input fsa-field__item" id="date-picker-static-display" aria-describedby="date-picker-static-display__help" aria-required="true" name="date-picker-static-display" type="text" value="">
<span class="fsa-field__help" id="date-picker-static-display__help">Example 05/14/1975</span>
</div>
<!-- Placed at bottom of page -->
<script>
datePickerController.createDatePicker({
formElements: { "date-picker-static-display": "%m/%d/%Y" },
disabledDays:[0,0,0,0,0,1,1],
staticPos: true
});
</script>
Disabled Static Calendar Location
Adding the disabled parameter to the <input> element disables both the <input> field and the entire Static Calendar.
Example 05/14/1975
<div class="fsa-field">
<label class="fsa-field__label" for="date-picker-static-display-disabled">Select Date</label>
<input placeholder="mm/dd/yyyy" disabled class="fsa-input fsa-field__item" id="date-picker-static-display-disabled" aria-describedby="date-picker-static-display-disabled__help" aria-required="true" name="date-picker-static-display-disabled" type="text" value="">
<span class="fsa-field__help" id="date-picker-static-display-disabled__help">Example 05/14/1975</span>
</div>
<!-- Placed at bottom of page -->
<script>
datePickerController.createDatePicker({
formElements: { "date-picker-static-display-disabled": "%m/%d/%Y" },
staticPos: true
});
</script>
Calendar with Status Bar
To augment the visual impact of date selection, you can add a status message, dynamically displayed beneath the calendar. Add the JavaScript method statusFormat to the initialized object, specifying a date format that follows the Date Formatting Options shown below. The below example uses "%l, %d%S %F %Y".
Example 05/14/1975
<div class="fsa-field">
<label class="fsa-field__label" for="date-picker-status">Select Date</label>
<input placeholder="mm/dd/yyyy" class="fsa-input fsa-field__item" id="date-picker-status" aria-describedby="date-picker-status__help" aria-required="true" name="date-picker-status" type="text" value="">
<span class="fsa-field__help" id="date-picker-status__help">Example 05/14/1975</span>
</div>
<!-- Placed at bottom of page -->
<script>
datePickerController.createDatePicker({
formElements: { "date-picker-status": "%m/%d/%Y" },
statusFormat:"%l, %d%S %F %Y"
});
</script>
Date Formatting Options
The following list of conversion specifiers are valid for use within the date format:
| Specifier | Description |
|---|---|
%d
|
Day of the month, 2 digits with leading zeros (01 – 31)
|
%j
|
Day of the month without leading zeros (1 – 31)
|
%m
|
Numeric representation of a month, with leading zeros |
%n
|
Numeric representation of a month, without leading zeros |
%Y
|
A full numeric representation of a year, 4 digits |
%y
|
A two digit representation of a year |
%l
|
A full textual representation of the day of the week (Monday – Sunday) |
%S
|
English ordinal suffix for the day of the month: st, nd, rd or th (e.g. "1st", "2nd", "3rd", "5th") |
%F
|
A full textual representation of a month, such as January or March |
Examples of Date Formats using Specifiers
| Date Format | Format Specifier Combination |
|---|---|
| MMDDYYYY |
%m%d%Y
|
| MM/DD/YYYY |
%m/%d/%Y
|
| MM-DD-YYYY |
%m-%d-%Y
|
| M/D/YY |
%n%j%y
|
| M.D.YYYY |
%n.%j.%Y
|
Keyboard Navigation
The following keyboard commands allows the user to navigate Date Picker’s calendar when in focus.
| Keystroke | Description |
|---|---|
| Goes to the same day of the week in the previous or next week respectively. If the user advances past the end of the month they continue into the next or previous month as appropriate. | |
| Advances one day to the next‚ also in a continuum. Visually focus is moved from day to day and wraps from row to row in a grid of days and weeks. | |
| Moves to the same date in the previous year | |
| Moves to the same date in the next year | |
| Home | Moves to the first day of the current month. |
| End | Moves to the last day of the current month. |
| Page Up | Moves to the same date in the previous month |
| Page Down | Moves to the same date in the next month |
| Enter | Selects the date that currently has focus. Keyboard focus will move back to the associated text field once the datepicker has closed. |
| Esc | In the case of a popup datepicker‚ closes the widget without any action. Keyboard focus will move back to the associated text field once the datepicker has closed. |
Accessibility
Always refer to the Accessibility Forms Guide for overall guidance.
If you customize the text inputs, ensure they continue to meet the the accessibility requirements that apply to all form controls.
- Form components must have an associated
<label>with matchingforattribute. - Do not use the
placeholderattribute as the sole label for accessibility reasons. In addition to not being a suitable replacement for the required<label>element, most browsers’ default rendering of placeholder text does not provide a high enough contrast ratio to sufficiently serve as the sole label. - Each field needs to be labeled for a screen reader and the labels for fields broken into segments are often not meaningful.
- Do not use JavaScript to auto advance the focus from one field to the next. This makes it difficult for keyboard-only users to navigate and correct mistakes.
- The above list of Keyboard Commands follows the recommended 508 Compliance standards.
General Guidance
- The Date Picker utilizes a navigation bar consisting of four arrows and a Today button. They are intended for navigation purposes within the Calendar. For example, selecting the “Today” button navigates the User to today’s date, though it does not select today’s date.
- Text inputs are among the easiest type of input for desktop users but are more difficult for mobile users.
- Only show error validation messages or styling after a user has interacted with a particular field; avoid significantly updating styles while a user is actively entering input.
- Do not use the
placeholderattribute in place of a<label>element. Its purposes is different: the standard<label>describes the role of the form element; that is, it indicates what kind of information is expected. Theplaceholderattribute is typically a hint about the format the content should take. There are cases in which the placeholder attribute is not displayed to the user (e.g. when input field has a value), so the form must be understandable without it.