Date Selection

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

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.

Variations

Variations

Text Input Optimized for Localization

This variation 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 variation 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 variation 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.

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.).

Developer Notes

Configurable Settings

When using the Spark Date Selection, there are many settings that can be configured to suit the application. The full variables are available in the dev documentation, but here are a few to keep in mind:

  • Selectable range: beginning, end
  • Unavailable dates within selectable range
  • 1-month or 2-month view (note: 2 month view collapses to 1-month on XS screen sizes)
  • Date format
  • Additional keyword/indicator
  • Advance by year/month

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">Departure</span>
    <a class="spark-input__addon spark-date__calendar-toggle" title="Show Calendar"><i class="spark-icon-calendar"></i></a>
  </label>

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

// jQuery
$('.spark-date').sparkDateInput();
$('.spark-date').sparkCalendarPopover();

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) or $(el).sparkCalendarPopover().

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

Many options can be passed to the Calendar Popover to configure the appearance and functionality.

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.
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.
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?
onChange function null A callback function for when the calendar value changes.

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">
    <input class="spark-input__field" type="date" role="textbox" data-show-date-as-text>
    <span class="spark-label">Departure</span>
    <a class="spark-input__addon spark-date__calendar-toggle" title="Show Calendar"><i class="spark-icon-calendar"></i></a>
  </label>

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

// jQuery
$('.spark-date').sparkDateInput();
$('.spark-date').sparkCalendarPopover();

Use data-show-date-as-text in spark-input__field to make this variation 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>
// Vanilla JS
var el = document.querySelector('.spark-date');
var dateInstance = new Spark.DateInput(el);

// jQuery
$('.spark-date').sparkDateInput();

The Date Input component can transform an ordinary type="date" input 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) or $(el).sparkDateInput(). Two options may be passed: a callback function for when the value changes (onChange) and the format of the select inputs (format: defaults to MM-DD-YYYY).

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-margin-bottom">
    <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">Departure</span>
      <a class="spark-input__addon spark-date__calendar-toggle" title="Show Calendar"><i class="spark-icon-calendar"></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">Arrival</span>
      <a class="spark-input__addon spark-date__calendar-toggle" title="Show Calendar"><i class="spark-icon-calendar"></i></a>
    </label>
  </div>

</div>
// 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]);

// jQuery
$('#calendar-popover-single-1, #calendar-popover-single-2').sparkDateInput();
$('#calendar-popover-single-1, #calendar-popover-single-2').sparkCalendarPopover();

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">Departure</span>
    <a class="spark-input__addon spark-date__calendar-toggle" title="Show Calendar"><i class="spark-icon-calendar"></i></a>
  </label>

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

// jQuery
$('.spark-date').sparkDateInput();
$('.spark-date').sparkCalendarPopover({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="2016-01-01" max="2016-02-06" role="textbox">
    <span class="spark-label">Departure</span>
  </label>

</div>
// Vanilla JS
var el = document.querySelector('.spark-date--select');
var dateInstance = new Spark.DateInput(el);

// jQuery
$('.spark-date--select').sparkDateInput();

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">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">End</span>
    </label>
  </div>

</div>
// Vanilla JS
var el = document.querySelector('.spark-date--select');
var dateInstance = new Spark.DateInput(el);

// jQuery
$('.spark-date--select').sparkDateInput();

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) or $(el).sparkDateInput(). Two options may be passed: a callback function for when the value changes (onChange) and the format of the select inputs (format: defaults to MM-DD-YYYY).