Skip Navigation

Date Selection

Date Selection allows users to specify a single date or a range of dates.

Available in React

Text Input with Calendar - Single Date Example

This date selection allows users to either type a date or access a calendar for selecting a date.


When to Use

  • When it is helpful for users to see a calendar. For example, when the corresponding day of the week and/or visual display of a calendar is relevant to the selection the user is making.

Examples

Examples

Text Input Optimized for Localization

This example automatically changes to display the name of the month after the user types a numeric value or selects a date from the calendar.


When to Use

  • This version is recommended when localization is a concern and/or when there may be confusion between months and days within a numeric-only date display.

When Not to Use

  • When a sense of the span of time (number of days, weeks) is helpful to users.

Text Input With Typeahead

This date selection allows users to type a numerically-formatted date. It may be used with or without a calendar.


When to Use

  • Use when the visual display of a calendar is not relevant to the date being entered.

Text Input with Calendar - Date Range

This date selection allows users to type a range of dates into a sequence of text input fields or access a calendar within each field to specify a date range. The text input fields may be separate fields (using the example above) or contiguous fields (shown below).


When to Use

  • When it is helpful for users to see a calendar. For example, when the corresponding days of the week and/or visual display of a calendar is relevant to the selection the user is making.

Text Input with Calendar with Advance by Month/Year

This date selection allows users to either type a date or access a calendar for selecting a date. In addition, it allows users to advance by month or year using a select dropdown within the context of the calendar display.


When to Use

  • Use this when it is likely that the user will want to advance by year and the display of a calendar is relevant to the decision the user is making. If a calendar is not helpful to the decision (for example, date of birth), a simple type-ahead text input or select input is recommended.

Text Input with Inline Calendar

This variation will show the calendar (by default) underneath the input field. It is embedded within the page rather than in a Popover.

Please enter a date


When to Use

  • When a Text Input with Calendar is inside a Popover or positioned at the bottom of a Modal causing the calendar to be cut off from the user’s view. View the Simple Form Modal to see this component in action.
  • If within a small field set or feature where the Inline Calendar requires additional visual weight or the visual prominence is preferred.

Select (Dropdown) - Single Date Example


When to Use

  • To select a date that is in the distant past or future. For example, date of birth.
  • To select a date when it is not necessary for the user to see a calendar view.

When Not to Use

  • When a user is likely to want to see the corresponding day of the week.
  • When a sense of the span of time (number of days, weeks) is helpful to users.

Select (Dropdown) - Date Range Selection


When to Use

To specify a start and end date range when viewing a calendar is not deemed necessary. For example, specifying start and end dates when filtering a large data set. In this scenario, a simple select with pre-determined ranges may also be considered (View Current Month, Current Year, Last Year, etc.).

Text Input w/ Error


Text Input w/ Error - Date Range

Please enter a date


Developer Notes

Configurable Settings

When working with the Spark Date Selection component, all instances are backed by an HTML input with type="date". Depending on which variant you are using, additional inputs will be created to capture the user’s input. Changes to these inputs will update the value in the original type="date" input.

The following options may be passed when using new Spark.DateInput(el, {});:

Name Type Default Description
isTypeahead boolean false Should this date input create a typeahead? If not passed directly, this value will betrue ifisSelect is nottrue or thespark-date--select class is not present on the element.
isSelect boolean false Should this date input create a series of select inputs? If not passed directly, this value will betrue if thespark-date--select class is present on the element.
format string 'MM-DD-YYYY' The date format used by the select or typeahead. 'MM', 'DD', 'YY' and 'YYYY' have special meaning. Everything else is considered part of the formatting. If not passed, it will be parsed from thedata-format attribute on theinput element if it's present.
textFormat string 'MM DD YYYY' The date format used when representing the date as text. For example, the default would render as 'Mar 13 2015'. If not passed, it will be parsed from thedata-text-format attribute on theinput element if it's present.
showDateAsText boolean false Should the typeahead text show as text when the element loses focus? If not passed, it will be parsed from thedata-show-date-as-text attribute on theinput element if it's present.
min string null A minimum valid date. If not passed, it will be parsed from themin attribute on theinput element if it's present.
max string null A maximum valid date. If not passed, it will be parsed from themax attribute on theinput element if it's present.
validate function null A function to run to validate the state of the input. It should call onValidate with the parameters outlined below.
onValidate function null A callback function run after validation has completed. Callback arguments are isValid, newValue, instance.
onChange function null A callback function run when the input value changes. Callback arguments are newValue, instance.
onFocus function null A callback function run when the input gains focus. Callback arguments are newValue, instance.
onBlur function null A callback function run when the input loses focus. Callback arguments are newValue, instance.

For all available methods and full API, refer to the component code on Bitbucket.

Text Input with Calendar - Single Date

<div class="col-sm-12 col-md-8 col-xl-6 spark-center-block container">

  <label class="spark-input spark-date example-simple-calendar">
    <input class="spark-input__field" type="date" role="textbox">
    <span class="spark-label">Depart</span>
    <a tabindex="0" class="spark-input__addon spark-date__calendar-toggle" aria-label="Show Calendar. Only available dates are displayed."><i class="spark-icon-calendar spark-icon--md"></i></a>
  </label>

</div>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-date');
var dateInstance = new Spark.DateInput(el);
var calInstance = new Spark.CalendarPopover(el);

Date Input components can be augmented by including a Calendar Popover component. In addition to creating a date typeahead using the techniques described above, calendar functionality can be added to an input by creating an instance of the Calendar Popover Javascript component by calling new Spark.CalendarPopover(el).

This component will listen for clicks on an element with a class of spark-date__calendar-toggle to show and hide a calendar popover.

The following options may be passed when using new CalendarPopover(el, {});:

Name Type Default Description
visibleCount number | array 1 The number of months visible when the popover is opened. Can be an array of values corresponding to each element passed.
autoAdvance boolean true Move to the next input in a range after a value is selected.
autoClose boolean true Close the popover after the last value has been selected.
anchorX string 'center' The default x-axis alignment of the popover. Can be left, right or center.
anchorY string 'bottom' The default y-axis alignment of the popover. Can be bottom, top or middle
closeDelay number 500 How long (in milliseconds) to wait before closing the popover. Works with autoClose.
min, mins object | array null The minimum date allowed. Can be an array of values corresponding to each element passed. If not passed, parsed from the attributes on an input.
max, maxes object | array null The maximum date allowed. Can be an array of values corresponding to each element passed. If not passed, parsed from the attributes on an input.
value, values object | array null The value to prepopulate. Can be an array of values corresponding to each element passed. If not passed, parsed from the attributes on an input.
daysDisabled object null A mapping of days which should not be selectable. Object structure is: {2016: {3: [9]}}
daysInfo object null A mapping of days which should have additional information. Object structure is: {2016: {3: {10: 'A note'}}}
quickJump boolean false Allow the user to quickly jump between months and years with select inputs inside the calendar popover. Only allowed when visibleCount === 1.
quickJumpRange number 50 Set a range of years to be used for the quickJump select. The range extends plus (+) and minus (-) from the date value supplied or from the current date visible in the Calendar Popover e.g. if no date value is set and the default range is in use, the quickJump select will cover 50 years before and 50 years after from the current day displayed in the Calendar Popover.
calendarEl element null The element to use for the calendar popover.
viewRange string 'month' Currently, only 'month' is supported.
animate boolean true Should the dates animate when they slide?
animationDuration number 100 The time, in milliseconds, of the slide animation between dates.
showOnFocus boolean false Should the calendar open when the corresponding input receives focus?
showTodayButton boolean false Determines whether a Today button should be shown at the bottom of the Calendar Popover. If not passed, it will be parsed from the data-show-today-button attribute on the spark-date element if it's present. If using the Calendar with Date Range variation, the data-show-today-button attribute only needs to be placed on the first spark-date element to appear on all Calendar Popovers.
todayButtonLabel string 'Select Today' The label of the Today button. If not passed, it will be parsed from the data-today-button-label attribute on the spark-date element if it's present. If using the Calendar with Date Range variation, the data-today-button-label attribute only needs to be placed on the first spark-date element to appear on all Calendar Popovers.
onChange function null A callback function for when the calendar value changes. Callback arguments are targetElement, newValue, instance.

Text Input with Inline Calendar

<div class="row">
  <div class="col-xs-12 col-lg-8 col-xl-6 spark-center-block">

    <label class="spark-input spark-date example-calendar-inline has-calendar-inline">
      <input class="spark-input__field" type="date" role="textbox">
      <span class="spark-label">Depart</span>
    </label>
    
  </div>
</div>

<style type="text/css">
  
</style>
// Vanilla JS
var inlineCalendar1 = document.querySelector('.example-calendar-inline');
if (inlineCalendar1) {
  cal = new Spark.CalendarInline(inlineCalendar1, { visibleCount: 1 });
}

Date Input components can be augmented by including an Inline Calendar component. In addition to creating a date typeahead using the techniques described above, calendar functionality can be added to an input by creating an instance of the Inline Calendar Javascript component by calling new Spark.CalendarInline(el).

The following options may be passed when using new CalendarInline(el, {});:

Name Type Default Description
visibleCount number | array 1 The number of months visible when the popover is opened. Can be an array of values corresponding to each element passed.
min, mins object | array null The minimum date allowed. Can be an array of values corresponding to each element passed. If not passed, parsed from the attributes on an input.
max, maxes object | array null The maximum date allowed. Can be an array of values corresponding to each element passed. If not passed, parsed from the attributes on an input.
value, values object | array null The value to prepopulate. Can be an array of values corresponding to each element passed. If not passed, parsed from the attributes on an input.
daysDisabled object null A mapping of days which should not be selectable. Object structure is: {2016: {3: [9]}}
daysInfo object null A mapping of days which should have additional information. Object structure is: {2016: {3: {10: 'A note'}}}
calendarEl element null The element to use for the calendar popover.
viewRange string 'month' Currently, only 'month' is supported.
animate boolean true Should the dates animate when they slide?
animationDuration number 100 The time, in milliseconds, of the slide animation between dates.
showTodayButton boolean false Determines whether a Today button should be shown at the bottom of the Inline Calendar. If not passed, it will be parsed from the data-show-today-button attribute on the spark-date element if it's present. If using the Calendar with Date Range variation, the data-show-today-button attribute only needs to be placed on the first spark-date element to appear on all Inline Calendars.
todayButtonLabel string 'Select Today' The label of the Today button. If not passed, it will be parsed from the data-today-button-label attribute on the spark-date element if it's present. If using the Calendar with Date Range variation, the data-today-button-label attribute only needs to be placed on the first spark-date element to appear on all Inline Calendars.
ariaSelectedLabel string 'Selected.' Accessible Label used in a Calendar to mark that the calendar date is selected. If used in a Calendar with Date Range this label will appear on dates that are between the start of the date range and the end of the date range.
ariaStartDateLabel string 'Selected as start date.' Accessible Label used Calendar with Date Range to mark the start of the date range.
ariaEndDateLabel string 'Selected as end date.' Accessible Label used Calendar with Date Range to mark the end of the date range.
onChange function null A callback function for when the calendar value changes. Callback arguments are targetElement, newValue, instance.

Text Input Optimized for Localization

<div class="col-sm-12 col-md-8 col-xl-6 spark-center-block container">

  <label class="spark-input spark-date example-simple-calendar-with-show-date">
    <input class="spark-input__field" type="date" role="textbox" data-show-date-as-text>
    <span class="spark-label">Depart</span>
    <a tabindex="0" class="spark-input__addon spark-date__calendar-toggle" aria-label="Show Calendar. Only available dates are displayed."><i class="spark-icon-calendar spark-icon--md"></i></a>
  </label>

</div>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-date');
var dateInstance = new Spark.DateInput(el);
var calInstance = new Spark.CalendarPopover(el);

Use data-show-date-as-text in spark-input__field to make this available. The format of the date text is MM DD YYYY.

Text Input with Typeahead

<div class="col-sm-12 col-md-8 col-xl-6 spark-center-block container">

  <label class="spark-input spark-date">
    <input class="spark-input__field" type="date" role="textbox">
    <span class="spark-label">Date of Birth</span>
  </label>

</div>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-date');
var dateInstance = new Spark.DateInput(el);

The Date Input component can also transform an input with type="date" into a series of text typeaheads. First, add a class of spark-date and to a regular Spark Input. Next, create an instance of the Date Input JavaScript component by calling new Spark.DateInput(el).

Text Input with Calendar - Date Range

<div class="col-sm-12 col-md-8 col-xl-6 spark-center-block container">

  <div class="spark-input-group spark-mar-b-1">
    <label class="spark-input-group__item spark-input-group__item--primary spark-input spark-date example-double-calendar-1">
      <input class="spark-input__field" type="date" role="textbox">
      <span class="spark-label">Depart</span>
      <a tabindex="0" class="spark-input__addon spark-date__calendar-toggle" aria-label="Show Calendar. Only available dates are displayed."><i class="spark-icon-calendar spark-icon--md"></i></a>
    </label>

    <label class="spark-input-group__item spark-input-group__item--primary spark-input spark-date example-double-calendar-2">
      <input class="spark-input__field" type="date" role="textbox">
      <span class="spark-label">Return</span>
      <a tabindex="0" class="spark-input__addon spark-date__calendar-toggle" aria-label="Show Calendar. Only available dates are displayed."><i class="spark-icon-calendar spark-icon--md"></i></a>
    </label>
  </div>

</div>

<style type="text/css">
  
</style>
// Vanilla JS
var el1 = document.getElementById('calendar-popover-single-1');
var el2 = document.getElementById('calendar-popover-single-2');
var dateInstance = new Spark.DateInput(el1);
var dateInstance2 = new Spark.DateInput(el2);
var calInstance = new Spark.CalendarPopover([el1, el2]);

When creating a range of inputs linked through a calendar, simply include multiple elements when instantiating the Javascript helper: new Spark.CalendarPopover([el1, el2]).

Text Input with Calendar - Single Selection with Advance by Month/Year

<div class="col-sm-12 col-md-8 col-xl-6 spark-center-block container">

  <label class="spark-input spark-date example-simple-calendar-prefilled">
    <input class="spark-input__field" type="date" value="2016-04-02" role="textbox">
    <span class="spark-label">Depart</span>
    <a tabindex="0" class="spark-input__addon spark-date__calendar-toggle" aria-label="Show Calendar. Only available dates are displayed."><i class="spark-icon-calendar spark-icon--md"></i></a>
  </label>

</div>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-date');
var dateInstance = new Spark.DateInput(el);
var calInstance = new Spark.CalendarPopover(el, {quickJump: true});

When the quickJump option is passed to the Calendar Popover constructor, the month and year are replaced with select inputs. How far a user can jump around in time is determined by the min and max value of the corresponding input. If no min or max is set, the maximum and minimum dates will be 50 years ahead and behind the current date selected.

Select (Dropdown) - Single Date Selection

<div class="col-sm-12 col-md-8 col-xl-6 spark-center-block container">

  <label class="spark-input spark-date spark-date--select">
    <input class="spark-input__field" type="date" min="2012-01-01" max="2022-02-06" role="textbox">
    <span class="spark-label" id="departure-date">Departure</span>
  </label>

</div>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-date--select');
var dateInstance = new Spark.DateInput(el);

When working with the Spark Date Selection component, all inputs are backed by an HTML input with type="date". Depending on which variation of the date selection you choose, additional inputs will be created to capture the user’s input. Changes to these inputs will update the value in the original type="date" input. You can see this behavior in action below.

Select (Dropdown) - Date Range Selection

<div class="col-sm-12 col-md-8 col-xl-6 spark-center-block container">

  <div class="row">
    <label class="col-xs-12 col-sm-6 spark-input spark-date spark-date--select">
      <input class="spark-input__field" type="date" value="2016-01-02" role="textbox">
      <span class="spark-label" id="start-date">Start</span>
    </label>
    <label class="col-xs-12 col-sm-6 spark-input spark-date spark-date--select">
      <input class="spark-input__field" type="date" value="2016-04-07" role="textbox">
      <span class="spark-label" id="end-date">End</span>
    </label>
  </div>

</div>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-date--select');
var dateInstance = new Spark.DateInput(el);

The Date Input component can transform an ordinary type="date" input into a series of select inputs. First, add a class of spark-date and spark-date--select to a regular Spark Input. Next, create an instance of the Date Input JavaScript component by calling new Spark.DateInput(el). If min and/or max dates are provided, only the year dropdown will be limited to the supplied dates.

Internationalization and Configuration

It is possible to configure both the names of the months and the names of the days of the week. setMonthNames, setMonthNamesShort, setDayNames and setDayNamesShort are methods available on the dateHelper object. For more details on the dateHelper object’s API, refer to the code on Bitbucket.

The day to use as the first of the week can also be configured. The default value is 0 for Sunday, but calling dateHelper.setWeekStartsOn() can change this behavior. Passing a value of 1 would set Monday to be the first day of the week. 2 would be Tuesday and so on.

Text Input w/ Error

<div class="col-sm-12 col-md-8 col-xl-6 spark-center-block container">

  <label class="spark-input spark-date" data-error>
    <input class="spark-input__field" type="date" role="textbox">
    <span class="spark-label">Date of Birth</span>
    <span class="spark-input__message">Please enter a date</span>
  </label>

</div>

<style type="text/css">
  
</style>
var el = document.querySelector('.spark-date');
new Spark.DateInput(el, {
onInput: function(value, inst) {
if(value.length === 8) {
inst.setErrorState(false);
}
else {
inst.setErrorState(true);
}
}
});
var calInstance = new Spark.CalendarPopover(el);

Text Input w/ Error - Date Range

Please enter a date 
<div class="col-sm-12 col-md-8 col-xl-6 spark-center-block container">

  <div class="spark-input-group spark-mar-b-1 row" data-error>
    <label class="spark-input-group__item spark-input-group__item--primary spark-input spark-date example-double-calendar-3 col-xs-12 col-sm-6" data-error>
      <input class="spark-input__field" type="date" role="textbox">
      <span class="spark-label">Depart</span>
      <a tabindex="0" class="spark-input__addon spark-date__calendar-toggle" aria-label="Show Calendar. Only available dates are displayed."><i class="spark-icon-calendar spark-icon--md"></i></a>
    </label>

    <label class="spark-input-group__item spark-input-group__item--primary spark-input spark-date example-double-calendar-4 col-xs-12 col-sm-6">
      <input class="spark-input__field" type="date" role="textbox" value="2016-01-01">
      <span class="spark-label">Return</span>
      <a tabindex="0" class="spark-input__addon spark-date__calendar-toggle" aria-label="Show Calendar. Only available dates are displayed."><i class="spark-icon-calendar spark-icon--md"></i></a>
    </label>

    <span class="spark-input__message">Please enter a date</span>
  </div>

</div>

<style type="text/css">
  
</style>
var linkedCalendar3 = document.querySelector('.example-double-calendar-3');
var linkedCalendar4 = document.querySelector('.example-double-calendar-4');
if (linkedCalendar3 && linkedCalendar4) {
new Spark.CalendarPopover([linkedCalendar3, linkedCalendar4], {visibleCount: 2});
}
//logic of custom validation, NOT INCLUDE in sabre-spark
var customValidation = function (a, b) {
var hasError = false;
for(var i=0;i<3;i++) {
if(a[i].value && b[i].value) {
continue;
}
else {
this.parentNode.setAttribute('data-error','');
hasError = true;
break;
}
}
if(!hasError) {
this.parentNode.removeAttribute('data-error');
}
}
var input11 = linkedCalendar3.querySelectorAll('.spark-input**field')[0];
var input12 = linkedCalendar3.querySelectorAll('.spark-input**field')[1];
var input13 = linkedCalendar3.querySelectorAll('.spark-input\_\_field')[2];

var input21 = linkedCalendar4.querySelectorAll('.spark-input**field')[0];
var input22 = linkedCalendar4.querySelectorAll('.spark-input**field')[1];
var input23 = linkedCalendar4.querySelectorAll('.spark-input\_\_field')[2];

input11.addEventListener('input', customValidation.bind(linkedCalendar3, [input11, input12, input13], [input21, input22, input23]));
input12.addEventListener('input', customValidation.bind(linkedCalendar3, [input11, input12, input13], [input21, input22, input23]));
input13.addEventListener('input', customValidation.bind(linkedCalendar3, [input11, input12, input13], [input21, input22, input23]));

input21.addEventListener('input', customValidation.bind(linkedCalendar4, [input11, input12, input13], [input21, input22, input23]));
input22.addEventListener('input', customValidation.bind(linkedCalendar4, [input11, input12, input13], [input21, input22, input23]));
input23.addEventListener('input', customValidation.bind(linkedCalendar4, [input11, input12, input13], [input21, input22, input23]));

Accessibility Notes

Text Input Date Selection

The text input variation of the Date Input component creates three fields used to display the month, day and year of the date entered. As these fields are generated on the fly using Javascript, aria-label attributes are also created to ensure that these fields have accessible labels that can be read by screen-readers and assistive devices. The value of this label is a combination of the label set on the Date Input’s spark-label element and the field’s date part e.g. Departure Month, where “Departure” is the label set on the component and “Month” is one of the three fields created, the others being “Day” and “Year.”

Select (Dropdown) Date Selection

The Select (Dropdown) variation of the Date Input functions in a similar manner as the text input variation above in that additional fields and labels are created to display the month, day, and year select dropdowns. In order to dynamically create the appropriate labels for each of the individual select dropdowns, it is important to set an id attribute on the spark-label element of the Date Input. This will then create a label similar to that of the text input variation above for each of the individual fields e.g. “Departure Month” or “Departure Year.”

<label class="spark-input spark-date spark-date--select">
<input class="spark-input__field" type="date" min="2012-01-01" max="2022-02-06" role="textbox">
<span class="spark-label" id="departure-date">Departure</span>
</label>

Calendar Popover

The Calendar Popover inherits some functionality from the Popover component, but also includes additional enhancements to ensure the contents of the Calendar are accessible to assistive technologies.

When using the Date Input component that has a Calendar, ensure that the spark-date__calendar-toggle element that toggles the calendar has a tabindex="0" attribute. This ensures that the toggle can be accessed via keyboard and the calendar displayed by hitting the Enter key when focused on it. It is also necessary to add an aria-label property to this element that informs non-sighted users that only available dates will be accessible on the calendar. This is because inactive or unavailable dates are skipped over when navigating via keyboard.

<label class="spark-input spark-date example-simple-calendar">
<input class="spark-input__field" type="date" role="textbox">
<span class="spark-label">Departure</span>
<a tabindex="0" class="spark-input__addon spark-date__calendar-toggle" aria-label="Show Calendar. Only available dates are displayed." title="Show Calendar"><i class="spark-icon-calendar spark-icon--md"></i></a>
</label>

The controls within the calendar such as the arrow navigation buttons and dates have additional ARIA attributes added to make the content accessible. These attributes include aria-label and aria-hidden, and will provide additional information for a date e.g. announcing the full date or identify a date as an inactive date and prevent its selection. This functionality is handled by Javascript and will not need to be set as part of instantiating the component.

Inline Calendar

The Inline Calendar includes enhancements to ensure the contents of the Calendar are accessible to assistive technologies.

The controls within the calendar such as the arrow navigation buttons and dates have additional ARIA attributes added to make the content accessible. These attributes include aria-label and aria-hidden, and will provide additional information for a date e.g. announcing the full date or identify a date as an inactive date and prevent its selection. This functionality is handled by Javascript and will not need to be set as part of instantiating the component.

The navigation of the Inline Calendar uses a combination of tab controls to navigate the months and keyboard arrow controls to navigate the dates within that month.