See what's coming soon with Carbon V10-beta.

Skip to main content
Date and time pickers allow users to select a single or a range of dates and times.

Simple date picker

Invalid date format.

Vanilla JS

<!-- Basic without calendar (mm/yy only) -->
<div class="bx--form-item">
  <div class="bx--date-picker bx--date-picker--simple bx--date-picker--short">
    <div class="bx--date-picker-container">
      <label for="date-picker-4" class="bx--label">Date Picker label</label>
      <input type="text" id="date-picker-4" class="bx--date-picker__input" pattern="\d{1,2}/\d{4}" placeholder="mm/yyyy" data-date-picker-input
      />
    </div>
  </div>
</div>

<!-- Basic without calendar -->
<div class="bx--form-item">
  <div class="bx--date-picker bx--date-picker--simple">
    <div class="bx--date-picker-container">
      <label for="date-picker-6" class="bx--label">Date Picker label</label>
      <input data-invalid type="text" id="date-picker-6" class="bx--date-picker__input" pattern="\d{1,2}/\d{1,2}/\d{4}" placeholder="mm/dd/yyyy"
        data-date-picker-input />
      <div class="bx--form-requirement">
        Invalid date format.
      </div>
    </div>
  </div>
</div>

Single date picker

Invalid date format.

Vanilla JS

<!-- Basic with calendar -->
<div class="bx--form-item">
  <div data-date-picker data-date-picker-type="single" class="bx--date-picker bx--date-picker--single">
    <div class="bx--date-picker-container">
      <svg data-date-picker-icon class="bx--date-picker__icon" width="14" height="16" viewBox="0 0 14 16">
        <path d="M0 5h14v1H0V5zm3-5h1v4H3V0zm7 0h1v4h-1V0zM0 2.5A1.5 1.5 0 0 1 1.5 1h11A1.5 1.5 0 0 1 14 2.5v12a1.5 1.5 0 0 1-1.5 1.5h-11A1.5 1.5 0 0 1 0 14.5v-12zm1 0v12a.5.5 0 0 0 .5.5h11a.5.5 0 0 0 .5-.5v-12a.5.5 0 0 0-.5-.5h-11a.5.5 0 0 0-.5.5z"
          fill-rule="nonzero" />
      </svg>
      <label for="date-picker-3" class="bx--label">Date Picker label</label>
      <input type="text" id="date-picker-3" class="bx--date-picker__input" pattern="\d{1,2}/\d{1,2}/\d{4}" placeholder="mm/dd/yyyy"
        data-date-picker-input />
    </div>
  </div>
</div>

<!-- Basic with calendar -->
<div class="bx--form-item">
  <div data-date-picker data-date-picker-type="single" class="bx--date-picker bx--date-picker--single">
    <div class="bx--date-picker-container">
      <svg data-date-picker-icon class="bx--date-picker__icon" width="14" height="16" viewBox="0 0 14 16">
        <path d="M0 5h14v1H0V5zm3-5h1v4H3V0zm7 0h1v4h-1V0zM0 2.5A1.5 1.5 0 0 1 1.5 1h11A1.5 1.5 0 0 1 14 2.5v12a1.5 1.5 0 0 1-1.5 1.5h-11A1.5 1.5 0 0 1 0 14.5v-12zm1 0v12a.5.5 0 0 0 .5.5h11a.5.5 0 0 0 .5-.5v-12a.5.5 0 0 0-.5-.5h-11a.5.5 0 0 0-.5.5z"
          fill-rule="nonzero" />
      </svg>
      <label for="date-picker-3" class="bx--label">Date Picker label</label>
      <input data-invalid type="text" id="date-picker-3" class="bx--date-picker__input" pattern="\d{1,2}/\d{1,2}/\d{4}" placeholder="mm/dd/yyyy"
        data-date-picker-input />
      <div class="bx--form-requirement">
        Invalid date format.
      </div>
    </div>
  </div>
</div>

Range date picker

Vanilla JS

<!-- Ranged -->
<div class="bx--form-item">
  <div data-date-picker data-date-picker-type="range" class="bx--date-picker bx--date-picker--range">
    <div class="bx--date-picker-container">
      <label for="date-picker-1" class="bx--label">Start date label</label>
      <input type="text" id="date-picker-1" class="bx--date-picker__input" pattern="\d{1,2}/\d{1,2}/\d{4}" placeholder="mm/dd/yyyy"
        data-date-picker-input-from />
    </div>
    <div class="bx--date-picker-container">
      <label for="date-picker-2" class="bx--label">End date label</label>
      <input type="text" id="date-picker-2" class="bx--date-picker__input" pattern="\d{1,2}/\d{1,2}/\d{4}" placeholder="mm/dd/yyyy"
        data-date-picker-input-to />
    </div>
    <svg data-date-picker-icon class="bx--date-picker__icon" width="14" height="16" viewBox="0 0 14 16">
      <path d="M0 5h14v1H0V5zm3-5h1v4H3V0zm7 0h1v4h-1V0zM0 2.5A1.5 1.5 0 0 1 1.5 1h11A1.5 1.5 0 0 1 14 2.5v12a1.5 1.5 0 0 1-1.5 1.5h-11A1.5 1.5 0 0 1 0 14.5v-12zm1 0v12a.5.5 0 0 0 .5.5h11a.5.5 0 0 0 .5-.5v-12a.5.5 0 0 0-.5-.5h-11a.5.5 0 0 0-.5.5z"
        fill-rule="nonzero" />
    </svg>
  </div>
</div>

Time picker

Invalid time.

Vanilla JS

<div class="bx--form-item">
  <div class="bx--time-picker">
    <div class="bx--time-picker__input">
      <label for="time-picker-1" class="bx--label">Select a time</label>
      <input id="time-picker-1" type="text" class="bx--time-picker__input-field" pattern="(1[012]|[1-9]):[0-5][0-9](\\s)?(?i)"
        placeholder="hh:mm" maxlength="5" />
      <div class="bx--form-requirement">
        Invalid time.
      </div>
    </div>
    <div class="bx--time-picker__select bx--select bx--select--inline">
      <label for="select-id-1" class="bx--label bx--visually-hidden">Select AM/PM</label>
      <select id="select-id-1" class="bx--select-input">
        <option class="bx--select-option" value="AM">AM</option>
        <option class="bx--select-option" value="PM">PM</option>
      </select>
        <svg class="bx--select__arrow" width="10" height="5" viewBox="0 0 10 5">
          <path d="M0 0l5 4.998L10 0z" fill-rule="evenodd" />
        </svg>
    </div>
    <div class="bx--time-picker__select bx--select bx--select--inline">
      <label for="select-id-2" class="bx--label bx--visually-hidden">Select time zone</label>
      <select id="select-id-2" class="bx--select-input">
        <option class="bx--select-option" value="option-1">Time zone 1</option>
        <option class="bx--select-option" value="option-2">Time zone 2</option>
        <option class="bx--select-option" value="option-3">Time zone 3</option>
      </select>
        <svg class="bx--select__arrow" width="10" height="5" viewBox="0 0 10 5">
          <path d="M0 0l5 4.998L10 0z" fill-rule="evenodd" />
        </svg>
    </div>
  </div>
</div>

Documentation

JavaScript

Getting component class reference

ES2015
import { DatePicker } from 'carbon-components';
With pre-build bundle (carbon-components.min.js)
var DatePicker = CarbonComponents.DatePicker;

Instantiating

// `#my-date-picker` is an element with `[data-date-picker]` attribute
DatePicker.create(document.getElementById('my-date-picker'));

Public Methods

Name Params Description
release Deletes the instance

Options

Option Default Selector Description
selectorInit [data-date-picker] Element for initializing instance
selectorDatePickerInput [data-date-picker-input] Input element
selectorDatePickerInputFrom [data-date-picker-input-from] For ranged calendars only: The "From date" input element
selectorDatePickerInputTo [data-date-picker-input-to] For ranged calendars only: The "To date" input element
selectorDatePickerIcon [data-date-picker-icon] Calendar icon
classCalendarContainer .bx--date-picker__calendar Class selector for the calendar container
classMonth .bx--date-picker__month Class selector for the calendar month
classWeekdays .bx--date-picker__weekdays Class selector for the calendar weekdays
classDays .bx--date-picker__days Class selector for the calendar days
classWeekday .bx--date-picker__weekday Class selector for a calendar weekday
classDay .bx--date-picker__day Class selector for a calendar day
attribType data-date-picker-type Specifies the calendar mode (single or range)
dateFormat 'm/d/Y' The date format given to the calendar instance

The date picker is built on top of Flatpickr, so many of the events and config options that come with Flatpickr is therefore available to the date picker options. This includes methods for setting a min date, max date, disabling date(s), specifiying a range of dates, and more.

Example - Getting notified of date picker dropdown being closed
// `#my-date-picker` is an element with `[data-date-picker]` attribute
DatePicker.create(document.getElementById('my-date-picker'), {
  onClose() {
    console.log('Date picker dropdown closed!');
  },
});

FAQ

Using and understanding Date Picker

There are 3 different date picker types:

Type data-date-picker-type
A simple date picker without a calendar No data attributes needed
A single date picker [data-date-picker-type="single"]
A ranged date picker [data-date-picker-type="range"]

The simple date picker is a text input without a calendar. You can specify the pattern for the text input to make sure the user enters the correct date format. The default regex pattern that ships with the simple date picker is \d{1,2}/\d{4} ('dd/yyyy' for short date pickers) and \d{1,2}/\d{1,2}/\d{4} ('dd/mm/yyyy' or mm/dd/yyyy). The simple date picker does not require any JavaScript.

The single date picker is a text input with a calendar instance attached to it. It also ships with a calendar icon inside the input field. The calendar will open when the input is focused, and the user can both type in a date or select a day from the calendar. The single date picker requires JavaScript, so the data attributes data-date-picker and data-date-picker-type="single" are required on the parent div, and the data attribute data-date-picker-input is required on the input field.

The ranged date picker has two text inputs with a ranged calendar instance attached to them. The ranged date picker requires JavaScript, so the data attributes data-date-picker and data-date-picker-type="range" are required on the parent div, and the data attributes data-date-picker-input-from and data-date-picker-input-to are required on the two input fields.

Localization

Date Picker supports localization, and you can specify the date format by overriding the component option dateFormat. Supported date formats are listed here.

To localize the date picker globally, please follow these instructions.