Skip to main contentCarbon Design System

Date picker

Simple date picker

Invalid date format.
Vanilla JS
React Angular Vue CodePen
Code:
<!-- 
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<!-- 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
React Angular Vue CodePen
Code:
<!--
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<!-- 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">
      <label for="date-picker-3" class="bx--label">Date Picker label</label>
      <div class="bx--date-picker-input__wrapper">
        <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 />
        <svg focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" data-date-picker-icon="true" class="bx--date-picker__icon" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M13,2h-2V1h-1v1H6V1H5v1H3C2.4,2,2,2.4,2,3v10c0,0.6,0.4,1,1,1h10c0.6,0,1-0.4,1-1V3C14,2.4,13.6,2,13,2z M13,13H3V6h10V13z M13,5H3V3h2v1h1V3h4v1h1V3h2V5z"></path></svg>
      </div>
    </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">
      <label for="date-picker-3" class="bx--label">Date Picker label</label>
      <div class="bx--date-picker-input__wrapper">
        <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 />
        <svg focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" data-date-picker-icon="true" class="bx--date-picker__icon" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M13,2h-2V1h-1v1H6V1H5v1H3C2.4,2,2,2.4,2,3v10c0,0.6,0.4,1,1,1h10c0.6,0,1-0.4,1-1V3C14,2.4,13.6,2,13,2z M13,13H3V6h10V13z M13,5H3V3h2v1h1V3h4v1h1V3h2V5z"></path></svg>
      </div>
      <div class="bx--form-requirement">
        Invalid date format.
      </div>
    </div>
  </div>
</div>

Range date picker

Vanilla JS
React Angular Vue CodePen
Code:
<!--
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<!-- 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>
      <div class="bx--date-picker-input__wrapper">
        <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 />
        <svg focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" data-date-picker-icon="true" class="bx--date-picker__icon" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M13,2h-2V1h-1v1H6V1H5v1H3C2.4,2,2,2.4,2,3v10c0,0.6,0.4,1,1,1h10c0.6,0,1-0.4,1-1V3C14,2.4,13.6,2,13,2z M13,13H3V6h10V13z M13,5H3V3h2v1h1V3h4v1h1V3h2V5z"></path></svg>
      </div>
    </div>
    <div class="bx--date-picker-container">
      <label for="date-picker-2" class="bx--label">End date label</label>
      <div class="bx--date-picker-input__wrapper">
        <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 />
        <svg focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" data-date-picker-icon="true" class="bx--date-picker__icon" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M13,2h-2V1h-1v1H6V1H5v1H3C2.4,2,2,2.4,2,3v10c0,0.6,0.4,1,1,1h10c0.6,0,1-0.4,1-1V3C14,2.4,13.6,2,13,2z M13,13H3V6h10V13z M13,5H3V3h2v1h1V3h4v1h1V3h2V5z"></path></svg>
      </div>
    </div>
  </div>
</div>

Single no label date picker

Invalid date format.
Vanilla JS
React CodePen
Code:
<!--
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<!-- 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 bx--date-picker--nolabel">
    <div class="bx--date-picker-container">
      <div class="bx--date-picker-input__wrapper">
        <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 />
        <svg focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" data-date-picker-icon="true" class="bx--date-picker__icon" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M13,2h-2V1h-1v1H6V1H5v1H3C2.4,2,2,2.4,2,3v10c0,0.6,0.4,1,1,1h10c0.6,0,1-0.4,1-1V3C14,2.4,13.6,2,13,2z M13,13H3V6h10V13z M13,5H3V3h2v1h1V3h4v1h1V3h2V5z"></path></svg>
      </div>
    </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 bx--date-picker--nolabel">
    <div class="bx--date-picker-container">
      <div class="bx--date-picker-input__wrapper">
        <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 />
        <svg focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" data-date-picker-icon="true" class="bx--date-picker__icon" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M13,2h-2V1h-1v1H6V1H5v1H3C2.4,2,2,2.4,2,3v10c0,0.6,0.4,1,1,1h10c0.6,0,1-0.4,1-1V3C14,2.4,13.6,2,13,2z M13,13H3V6h10V13z M13,5H3V3h2v1h1V3h4v1h1V3h2V5z"></path></svg>
      </div>
      <div class="bx--form-requirement">
        Invalid date format.
      </div>
    </div>
  </div>
</div>

Time picker

Invalid time.
Invalid time.
Vanilla JS
React Vue CodePen
Code:
<!--
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<div class="bx--form-item">
  <label for="time-picker-1" class="bx--label">Select a time</label>
  <div class="bx--time-picker">
    <div class="bx--time-picker__input">
      <input id="time-picker-1" type="text" class="bx--text-input bx--time-picker__input-field"
        pattern="(1[012]|[1-9]):[0-5][0-9](\\s)?" placeholder="hh:mm" maxlength="5" />
    </div>
    <div class="bx--time-picker__select bx--select">
      <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 focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" class="bx--select__arrow" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 11L3 6 3.7 5.3 8 9.6 12.3 5.3 13 6z"></path></svg>
    </div>
    <div class="bx--time-picker__select bx--select">
      <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 focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" class="bx--select__arrow" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 11L3 6 3.7 5.3 8 9.6 12.3 5.3 13 6z"></path></svg>
    </div>
  </div>
</div>
<div class="bx--form-item">
  <label for="time-picker-2" class="bx--label">Select a time</label>
  <div class="bx--time-picker" data-invalid>
    <div class="bx--time-picker__input">
      <input id="time-picker-2" type="text" class="bx--text-input bx--time-picker__input-field"
        pattern="(1[012]|[1-9]):[0-5][0-9](\\s)?" placeholder="hh:mm" maxlength="5" />
    </div>
    <div class="bx--time-picker__select bx--select">
      <label for="select-id-3" class="bx--label bx--visually-hidden">Select AM/PM</label>
      <select id="select-id-3" class="bx--select-input">
        <option class="bx--select-option" value="AM">AM</option>
        <option class="bx--select-option" value="PM">PM</option>
      </select>
      <svg focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" class="bx--select__arrow" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 11L3 6 3.7 5.3 8 9.6 12.3 5.3 13 6z"></path></svg>
    </div>
    <div class="bx--time-picker__select bx--select">
      <label for="select-id-4" class="bx--label bx--visually-hidden">Select time
        zone</label>
      <select id="select-id-4" 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 focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" class="bx--select__arrow" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 11L3 6 3.7 5.3 8 9.6 12.3 5.3 13 6z"></path></svg>
    </div>
  </div>
  <div class="bx--form-requirement">
    Invalid time.
  </div>
</div>
<div class="bx--form-item">
  <label for="time-picker-3" class="bx--label bx--label--disabled">Select a time</label>
  <div class="bx--time-picker">
    <div class="bx--time-picker__input">
      <input id="time-picker-3" type="text" class="bx--text-input bx--time-picker__input-field"
        pattern="(1[012]|[1-9]):[0-5][0-9](\\s)?" placeholder="hh:mm" maxlength="5" disabled />
    </div>
    <div class="bx--time-picker__select bx--select">
      <label for="select-id-5" class="bx--label bx--visually-hidden">Select AM/PM</label>
      <select id="select-id-5" class="bx--select-input" disabled>
        <option class="bx--select-option" value="AM">AM</option>
        <option class="bx--select-option" value="PM">PM</option>
      </select>
      <svg focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" class="bx--select__arrow" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 11L3 6 3.7 5.3 8 9.6 12.3 5.3 13 6z"></path></svg>
    </div>
    <div class="bx--time-picker__select bx--select">
      <label for="select-id-6" class="bx--label bx--visually-hidden">Select time
        zone</label>
      <select id="select-id-6" class="bx--select-input" disabled>
        <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 focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" class="bx--select__arrow" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 11L3 6 3.7 5.3 8 9.6 12.3 5.3 13 6z"></path></svg>
    </div>
  </div>
</div>
<div class="bx--form-item">
  <label for="time-picker-4" class="bx--label bx--label--disabled">Select a time</label>
  <div class="bx--time-picker" data-invalid>
    <div class="bx--time-picker__input">
      <input id="time-picker-4" type="text" class="bx--text-input bx--time-picker__input-field"
        pattern="(1[012]|[1-9]):[0-5][0-9](\\s)?" placeholder="hh:mm" maxlength="5" disabled />
    </div>
    <div class="bx--time-picker__select bx--select">
      <label for="select-id-7" class="bx--label bx--visually-hidden">Select AM/PM</label>
      <select id="select-id-7" class="bx--select-input" disabled>
        <option class="bx--select-option" value="AM">AM</option>
        <option class="bx--select-option" value="PM">PM</option>
      </select>
      <svg focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" class="bx--select__arrow" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 11L3 6 3.7 5.3 8 9.6 12.3 5.3 13 6z"></path></svg>
    </div>
    <div class="bx--time-picker__select bx--select">
      <label for="select-id-8" class="bx--label bx--visually-hidden">Select time
        zone</label>
      <select id="select-id-8" class="bx--select-input" disabled>
        <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 focusable="false" preserveAspectRatio="xMidYMid meet" style="will-change: transform;" xmlns="http://www.w3.org/2000/svg" class="bx--select__arrow" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 11L3 6 3.7 5.3 8 9.6 12.3 5.3 13 6z"></path></svg>
    </div>
  </div>
  <div class="bx--form-requirement">
    Invalid time.
  </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.

Edit this page on GitHub
Previous
Components: Data table
Next
Date picker: Usage