Skip to main content

DateTime picker

The datetime picker is used for selecting a single date or a single time. Clicking the entry point expands a picker surface for the user to make a date or time selection. The picker overlays other UI; it doesn’t push other UI out of the way. After user makes their selection, the entry point displays the chosen date or time.

Caution: our framework does NOT deliver the content for any of the datetime picker strings. This is due to the fact that generating content is complex from a localization perspective and is outside the scope of the framework. We deliver the markup needed & the CSS that will make it render properly, but a team using this component must take on the burden of delivering strings to the client. For a JavaScript library for internationalization and localization go to https://github.com/jquery/globalize.

Example

Date control header
Different date time types on a default theme

Best practices

Use the datetime picker when the user is required to specify a date or time or when they might have a specific date or time in mind that they want the workflow to utilize.

Do

  • Use for selecting a single date or a single time.
  • For smaller viewports and touch-only environments, use the datetime picker (with date format) instead of the calendar component. Datetime picker offers greater precision for selecting specific values due to the larger target areas.
  • The format used in the picker should reflect the appropriate format for the locale. For example, in Europe the 24-hour clock is a more widely used format than the 12-hour clock used in the U.S. Also, the date format in most European locales is dd/mm/yyyy instead of mm/dd/yyyy which is used more often in the U.S.

Don’t

  • Don’t use the datetime picker to display the current time of day where it is updated dynamically as the time of day changes.
  • Don’t use the component if you don’t intend the user to have the option to change the date or time.
  • Don’t use the component for gating content depending on the user’s age, use age gate instead.

Also known as

Date picker
Time picker

Related

Label

Options

  • Date Picker: To set date mode add data-date-time-picker="date".
  • 12-Hour Time Picker: To set 12-hour time mode add data-date-time-picker="time12".
  • 24-Hour Time Picker: To set 24-hour time mode add data-date-time-picker="time24".
  • Default Date/Time: Set aria-label and value of buttons to the desired default date/time.
  • Localized AM/PM: To allow localization of the morning and evening time designators, add the attribute data-meridiem to the unordered list element contained by the div with the data-date-time-picker attribute set to "am&pm". The data-meridiem attribute has two values: the first is the local morning designator and the second is the local evening designator. These two strings are separated by an & character. For example, in Greek: data-meridiem="π.µ.&µ.µ."

Development

Code and preview

Date picker

Date control label
<fieldset>
    <legend class="c-label" id="dtPickerDate">Date control label</legend>
    <div class="c-date-time-picker" data-date-time-picker="date">
        <button data-date-time-picker="month" data-formatter-aria-label="Month: {0}" aria-label="Month: March" data-active-value="March">March</button>
        <button data-date-time-picker="day" data-formatter-aria-label="Day: {0}" aria-label="Day: 11" data-active-value="11">11</button>
        <button data-date-time-picker="year" data-formatter-aria-label="Year: {0}" aria-label="Year: 2016" data-active-value="2016">2016</button>
        <div data-date-time-picker="date-selector" aria-hidden="true">
            <div data-date-time-picker="month">
                <button aria-label="Scroll Up" tabindex="-1"></button>
                <ul role="listbox" aria-label="Months" data-months="January,February,March,April,May,June,July,August,September,October,November,December">
                    <li role="option" aria-selected="false">October</li>
                    <li role="option" aria-selected="false">November</li>
                    <li role="option" class="f-js-last" aria-selected="false">December</li>
                    <li role="option" aria-selected="false">January</li>
                    <li role="option" aria-selected="false">February</li>
                    <li role="option" aria-selected="true" tabindex="0">March</li>
                    <li role="option" aria-selected="false">April</li>
                    <li role="option" aria-selected="false">May</li>
                    <li role="option" aria-selected="false">June</li>
                    <li role="option" aria-selected="false">July</li>
                    <li role="option" aria-selected="false">August</li>
                </ul>
                <button aria-label="Scroll Down" tabindex="-1"></button>
            </div>
            <div data-date-time-picker="day">
                <button aria-label="Scroll Up" tabindex="-1"></button>
                <ul aria-label="Day" role="listbox"></ul>
                <button aria-label="Scroll Down" tabindex="-1"></button>
            </div>
            <div data-date-time-picker="year">
                <button aria-label="Scroll Up" tabindex="-1"></button>
                <ul aria-label="Year" role="listbox"></ul>
                <button aria-label="Scroll Down" tabindex="-1"></button>
            </div>
            <span></span>
            <button data-date-time-picker="apply" class="c-glyph glyph-accept" aria-label="Apply" title="Apply"></button>
            <button data-date-time-picker="cancel" class="c-glyph glyph-cancel" aria-label="Cancel" title="Cancel"></button>
        </div>
    </div>
</fieldset>

Time picker (12hr)

Time control label
<fieldset>
    <legend class="c-label" id="dtPickerTime12">Time control label</legend>
    <div class="c-date-time-picker" data-date-time-picker="time">
        <button data-date-time-picker="hour" data-formatter-aria-label="Hour: {0}" aria-label="Hour: 5" data-active-value="5">5</button>
        <button data-date-time-picker="minute" data-formatter-aria-label="Minutes: {0}" aria-label="Minutes: 52" data-active-value="52">52</button>
        <button data-date-time-picker="ampm" data-formatter-aria-label="AM/PM: {0}" aria-label="AM/PM: AM" data-active-value="AM">AM</button>
        <div data-date-time-picker="time-selector12" aria-hidden="true">
            <div data-date-time-picker="hour">
                <button aria-label="Scroll Up" tabindex="-1"></button>
                <ul aria-label="Hour"></ul>
                <button aria-label="Scroll Down" tabindex="-1"></button>
            </div>
            <div data-date-time-picker="minute">
                <button aria-label="Scroll Up" tabindex="-1"></button>
                <ul aria-label="Minute"></ul>
                <button aria-label="Scroll Down" tabindex="-1"></button>
            </div>
            <div data-date-time-picker="ampm">
                <button aria-label="Scroll Up" tabindex="-1"></button>
                <ul aria-label="AM/PM" data-meridiem="AM&PM"></ul>
                <button aria-label="Scroll Down" tabindex="-1"></button>
            </div>
            <span></span>
            <button data-date-time-picker="apply" class="c-glyph glyph-accept" aria-label="Apply" title="Apply"></button>
            <button data-date-time-picker="cancel" class="c-glyph glyph-cancel" aria-label="Cancel" title="Cancel"></button>
        </div>
    </div>
</fieldset>

Time picker (24hr)

24 Hour Time control label
<fieldset>
    <legend class="c-label" id="dtPickerTime24">24 Hour Time control label</legend>
    <div class="c-date-time-picker" data-date-time-picker="time24">
        <button data-date-time-picker="hour24" data-formatter-aria-label="Hour: {0}" aria-label="Hour: 12" data-active-value="12">12</button>
        <button data-date-time-picker="minute24" data-formatter-aria-label="Minutes: {0}" aria-label="Minutes: 50" data-active-value="50">50</button>
        <div data-date-time-picker="time-selector24" aria-hidden="true">
            <div data-date-time-picker="hour24">
                <button aria-label="Scroll Up" tabindex="-1"></button>
                <ul></ul>
                <button aria-label="Scroll Down" tabindex="-1"></button>
            </div>
            <div data-date-time-picker="minute24">
                <button aria-label="Scroll Up" tabindex="-1"></button>
                <ul></ul>
                <button aria-label="Scroll Down" tabindex="-1"></button>
            </div>
            <span></span>
            <button data-date-time-picker="apply" class="c-glyph glyph-accept" aria-label="Apply" title="Apply"></button>
            <button data-date-time-picker="cancel" class="c-glyph glyph-cancel" aria-label="Cancel" title="Cancel"></button>
        </div>
    </div>
</fieldset>