Date pickers

Best practices

A date picker is an input field that expands and allows users to select a single date or date range (by selecting a start and end date). As with a text input field, a date picker should have a label and, if necessary, helper text. Date picker fields should always include a calendar icon.

Selecting the calendar icon in the text field opens the calendar view. The current date should always be underlined with the number displayed using a heavier weight. Previous and next arrows allow users to move through the months of the year. When a date is selected it becomes highlighted.

Date ranges

When a range is required, users will be asked to pick a start and end date. The behaviour for this scenario matches single date selection with a few exceptions:

The calendar view should use a label to inform the users which date they’re selecting (start or end).
After selecting the first date in the range, users should be automatically transitioned to a state where they’ll select the second date. The first date should always be visible and clearly communicated.

How it works

Our date picker is implemented using Bootstrap-datepicker. It is our only component that relies on JavaScripts outside of Bootstraps JavaScripts libraries. See their docs for further options, methods, and documentation.

French

The date picker will display French wording when <html lang="fr-ca">.

JavaScript

Required JavaScript can be accessed via CDN:

<!-- Date picker https://github.com/eternicode/bootstrap-datepicker -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-datepicker/1.8.0/js/bootstrap-datepicker.min.js"></script>

Custom styling

The date picker has been styled to match The City of Winnipeg brand. All required CSS is included here inside _sass/components/_datepicker.scss.

Single date example

Date

<div class="row">
  <div class="col-sm-6">
    <label for="date">Date</label>
    <div class="input-group mb-3">
      <input id="date" type="text" class="form-control datePicker" aria-label="Select a date">
      <div class="input-group-append input-group-addon">
        <button class="btn btn-outline-secondary datePickerTrigger" type="button"><i aria-label="Select date" class="far fa-calendar-alt"></i></button>
      </div>
    </div>
  </div>
</div>

Call the datepicker via JavaScript, set the date picker options, and set the input button as a secondary trigger:

//----- Enable single date picker
$('.datePicker').datepicker({
  format: 'mm/dd/yyyy',
  startDate: '-3d',
  todayHighlight: true,
  daysOfWeekDisabled: '0,6'
});

// Single date picker trigger
$('.datePickerTrigger').click(function() {
  $(this).closest('.input-group').find('.datePicker').datepicker('show');
})

Date range example

Start date

End date

<div class="row dateRange">
  <div class="col-sm-6">
    <label for="startDate">Start date</label>
    <div class="input-group mb-3">
      <input type="text" class="form-control dateRangeInput" id="startDate">
      <div class="input-group-append input-group-addon">
        <button class="btn btn-outline-secondary dateRangeTrigger" type="button"><i aria-label="Select start date" class="far fa-calendar-alt"></i></button>
      </div>
    </div>
  </div>
  <div class="col-sm-6">
    <label for="endDate">End date</label>
    <div class="input-group mb-3">
      <input type="text" class="form-control dateRangeInput" id="endDate">
      <div class="input-group-append input-group-addon">
        <button class="btn btn-outline-secondary dateRangeTrigger" type="button"><i aria-label="Select end date" class="far fa-calendar-alt"></i></button>
      </div>
    </div>
  </div>
</div>

Call the datepicker range inputs via JavaScript and set the input button as a secondary trigger:

//----- Enable date range 
$('.dateRange').datepicker({
  inputs: $('.dateRangeInput')
});

// Date range trigger
$('.dateRangeTrigger').click(function() {
  $(this).closest('.input-group').find('.dateRangeInput').datepicker('show');
})