CenturyLink Logo
CenturyLink
Lumen Logo
Lumen
Lumen Enterprise Portal Logo
Lumen Enterprise Portal

Date picker

Date picker allows users to enter a date through text input or choose a date from a calendar.

Examples

Base

Date
<chi-label for="date">Date</chi-label>
<chi-date-picker id="date"></chi-date-picker>
This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.
<div class="chi-form__item">
  <label class="chi-label" for="datepicker-1">Date</label>
  <div class="chi-input__wrapper -icon--right">
    <input id="datepicker-1" type="text" class="chi-input" placeholder="MM/DD/YYYY">
    <i class="chi-icon icon-date" aria-hidden="true"></i>
  </div>
</div>

<script>chi.datePicker(document.getElementById('datepicker-1'));</script>

Disabled

Date
<chi-label for="date-2">Date</chi-label>
<chi-date-picker id="date-2" disabled></chi-date-picker>
This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.
<div class="chi-form__item">
  <label class="chi-label" for="datepicker-2">Date</label>
  <div class="chi-input__wrapper -disabled -icon--right">
    <input id="datepicker-2" type="text" class="chi-input" placeholder="MM/DD/YYYY" disabled>
    <i class="chi-icon icon-date" aria-hidden="true"></i>
  </div>
</div>

<script>chi.datePicker(document.getElementById('datepicker-2'));</script>

Value, min and max options

Date
<chi-label for="date-3">Date</chi-label>
<chi-date-picker id="date-3" value="01/24/2024" min="01/14/2024" max="02/07/2024">
This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.
<div class="chi-form__item">
  <label class="chi-label" for="datepicker-3">Date</label>
  <div class="chi-input__wrapper -icon--right">
    <input id="datepicker-3" type="text" class="chi-input" value="01/24/2024" min="01/14/2024" max="02/07/2024" placeholder="MM/DD/YYYY">
    <i class="chi-icon icon-date" aria-hidden="true"></i>
  </div>
</div>

<script>chi.datePicker(document.getElementById('datepicker-3'));</script>

<!-- Or configure programmatically -->
<script>
  chi.datePicker(
    document.getElementById('datepicker-3'),
    {
      date: '01/24/2024',
      min: '01/24/2024'
    }
);
</script>

Excluded week days

Specify which week days to disable by using excluded-weekdays="0, 6" attribute

Date
<chi-label for="date-excluded-weekdays">Date</chi-label>
<chi-date-picker id="date-excluded-weekdays" excluded-weekdays="0, 6"></chi-date-picker>

Excluded dates

Specify which dates to disable by using excluded-dates="01/24/2024, 03/25/2024" attribute
Separate dates with a comma

Date
<chi-label for="date-excluded-dates">Date</chi-label>
<chi-date-picker id="date-excluded-dates" value="01/05/2024" excluded-dates="01/24/2024, 03/25/2024, 07/03/2024, 09/12/2024, 12/12/2024"></chi-date-picker>

Excluded dates and week days

Disable dates - excluded-dates="02/23/2024, 05/24/2024"
Disable days - excluded-weekdays="0, 6"

Date
<chi-label for="date-excluded-days-dates">Date</chi-label>
<chi-date-picker id="date-excluded-days-dates" excluded-weekdays="0, 6" excluded-dates="02/23/2024, 05/24/2024, 07/03/2024, 09/12/2024, 12/12/2024"></chi-date-picker>

Message

Use the helper-message attribute to provide users with additional information, validation feedback, and other helpful information.

Date
<chi-label for="date-message">Date</chi-label>
<chi-date-picker id="date-message" helper-message="Optional helper message"></chi-date-picker>
This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.
<div class="chi-form__item">
  <label class="chi-label" for="datepicker-message">Date</label>
  <div class="chi-input__wrapper -icon--right">
    <input id="datepicker-message" type="text" class="chi-input" placeholder="MM/DD/YYYY">
    <i class="chi-icon icon-date" aria-hidden="true"></i>
  </div>
  <div class="chi-label -status">Optional helper message</div>
</div>

<script>chi.datePicker(document.getElementById('datepicker-message'));</script>

Error

Use the danger state to provide feedback to users when date fails to validate. To meet accessibility requirements, danger date picker must include an error message explaining the failure and/or how to correct it.

Date
<chi-label for="date-error">Date</chi-label>
<chi-date-picker id="date-error" state="danger" helper-message="Please enter a date"></chi-date-picker>
This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.
<div class="chi-form__item">
  <label class="chi-label" for="datepicker-error">Date</label>
  <div class="chi-input__wrapper -icon--right">
    <input id="datepicker-error" type="text" class="chi-input -danger" placeholder="MM/DD/YYYY">
    <i class="chi-icon icon-date" aria-hidden="true"></i>
  </div>
  <div class="chi-label -status -danger">
    <i class="chi-icon icon-circle-warning" aria-hidden="true"></i>
    Please select a date
  </div>
</div>

<script>chi.datePicker(document.getElementById('datepicker-error'));</script>

Date Time

Date Time
<chi-label for="date-time">Date</chi-label>
<chi-date-picker id="date-time" mode="datetime"></chi-date-picker>

Date Time stepped

Minutes can be shown in steps of 5, 10, 15, 20, or 30 minutes or seconds. Use the property minutes-step="value" to define the step for the minutes (defaults to 15 min) if no value is provided.

Date Time
<chi-label for="date-time">Date</chi-label>
<chi-date-picker id="date-time" mode="datetime" minutes-step="5"></chi-date-picker>

Multiple dates

Use the attribute multiple to allow the user to select multiple dates.

Date
<chi-label for="multiple-dates">Date</chi-label>
<chi-date-picker id="multiple-dates" multiple></chi-date-picker>

Calendar

An example of a date picker calendar not attached to any element.

Base

<chi-date></chi-date>
This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.

Use the classes -month-starts-on-sun, -month-starts-on-mon, -month-starts-on-tue, -month-starts-on-wed, -month-starts-on-thu, -month-starts-on-fri and -month-starts-on-sat to locate the first day in the correct cell.
Use the classes -week-starts-on-sun or -week-starts-on-mon to fit the week definition of the desired locale.
Use the class -today for the current date
<div class="chi-datepicker -week-starts-on-sun -month-starts-on-wed">
  <div class="chi-datepicker__month-row">
    <div class="prev">
      <i class="chi-icon icon-chevron-left -sm" aria-hidden="true"></i>
    </div>
    <div class="chi-datepicker__month">
      November 2024
    </div>
    <div class="next">
      <i class="chi-icon icon-chevron-right -sm" aria-hidden="true"></i>
    </div>
  </div>
  <div class="chi-datepicker__day-names">
    <div class="chi-datepicker__week-day">
      S
    </div>
    <div class="chi-datepicker__week-day">
      M
    </div>
    <div class="chi-datepicker__week-day">
      T
    </div>
    <div class="chi-datepicker__week-day">
      W
    </div>
    <div class="chi-datepicker__week-day">
      T
    </div>
    <div class="chi-datepicker__week-day">
      F
    </div>
    <div class="chi-datepicker__week-day">
      S
    </div>
  </div>
  <div class="chi-datepicker__days">
    <div class="chi-datepicker__day">1</div>
    <div class="chi-datepicker__day">2</div>
    <div class="chi-datepicker__day">3</div>
    <div class="chi-datepicker__day">4</div>
    <div class="chi-datepicker__day">5</div>
    <div class="chi-datepicker__day">6</div>
    <div class="chi-datepicker__day">7</div>
    <div class="chi-datepicker__day">8</div>
    <div class="chi-datepicker__day">9</div>
    <div class="chi-datepicker__day">10</div>
    <div class="chi-datepicker__day">11</div>
    <div class="chi-datepicker__day">12</div>
    <div class="chi-datepicker__day">13</div>
    <div class="chi-datepicker__day">14</div>
    <div class="chi-datepicker__day">15</div>
    <div class="chi-datepicker__day">16</div>
    <div class="chi-datepicker__day">17</div>
    <div class="chi-datepicker__day">18</div>
    <div class="chi-datepicker__day">19</div>
    <div class="chi-datepicker__day">20</div>
    <div class="chi-datepicker__day">21</div>
    <div class="chi-datepicker__day">22</div>
    <div class="chi-datepicker__day">23</div>
    <div class="chi-datepicker__day">24</div>
    <div class="chi-datepicker__day">25</div>
    <div class="chi-datepicker__day">26</div>
    <div class="chi-datepicker__day">27</div>
    <div class="chi-datepicker__day">28</div>
    <div class="chi-datepicker__day">29</div>
    <div class="chi-datepicker__day">30</div>
  </div>
</div>

Active

<chi-date value="05/15/2024"></chi-date>
This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.

Use class -active for the selected date
<div class="chi-datepicker -week-starts-on-sun -month-starts-on-wed">
  <div class="chi-datepicker__month-row">
    <div class="prev"><i class="chi-icon icon-chevron-left -sm" aria-hidden="true"></i></div>
    <div class="chi-datepicker__month">May 2024</div>
    <div class="next"><i class="chi-icon icon-chevron-right -sm" aria-hidden="true"></i></div>
  </div>
  <div class="chi-datepicker__day-names">
    <div class="chi-datepicker__week-day">S</div>
    <div class="chi-datepicker__week-day">M</div>
    <div class="chi-datepicker__week-day">T</div>
    <div class="chi-datepicker__week-day">W</div>
    <div class="chi-datepicker__week-day">T</div>
    <div class="chi-datepicker__week-day">F</div>
    <div class="chi-datepicker__week-day">S</div>
  </div>
  <div class="chi-datepicker__days">
    <div class="chi-datepicker__day">1</div>
    <div class="chi-datepicker__day">2</div>
    <div class="chi-datepicker__day">3</div>
    <div class="chi-datepicker__day">4</div>
    <div class="chi-datepicker__day">5</div>
    <div class="chi-datepicker__day">6</div>
    <div class="chi-datepicker__day">7</div>
    <div class="chi-datepicker__day">8</div>
    <div class="chi-datepicker__day">9</div>
    <div class="chi-datepicker__day">10</div>
    <div class="chi-datepicker__day">11</div>
    <div class="chi-datepicker__day">12</div>
    <div class="chi-datepicker__day">13</div>
    <div class="chi-datepicker__day">14</div>
    <div class="chi-datepicker__day -active">15</div>
    <div class="chi-datepicker__day">16</div>
    <div class="chi-datepicker__day">17</div>
    <div class="chi-datepicker__day">18</div>
    <div class="chi-datepicker__day">19</div>
    <div class="chi-datepicker__day">20</div>
    <div class="chi-datepicker__day">21</div>
    <div class="chi-datepicker__day">22</div>
    <div class="chi-datepicker__day">23</div>
    <div class="chi-datepicker__day">24</div>
    <div class="chi-datepicker__day">25</div>
    <div class="chi-datepicker__day">26</div>
    <div class="chi-datepicker__day">27</div>
    <div class="chi-datepicker__day">28</div>
    <div class="chi-datepicker__day">29</div>
    <div class="chi-datepicker__day">30</div>
    <div class="chi-datepicker__day">31</div>
  </div>
</div>

Multiple active dates

Specify multiple active dates by separating the dates with a comma
<chi-date value="03/10/2024,03/11/2024,03/12/2024" multiple></chi-date>
Use class -active for the selected date
<div class="chi-datepicker -week-starts-on-sun -month-starts-on-wed">
  <div class="chi-datepicker__month-row">
    <div class="prev"><i class="chi-icon icon-chevron-left -sm" aria-hidden="true"></i></div>
    <div class="chi-datepicker__month">March 2024</div>
    <div class="next"><i class="chi-icon icon-chevron-right -sm" aria-hidden="true"></i></div>
  </div>
  <div class="chi-datepicker__day-names">
    <div class="chi-datepicker__week-day">S</div>
    <div class="chi-datepicker__week-day">M</div>
    <div class="chi-datepicker__week-day">T</div>
    <div class="chi-datepicker__week-day">W</div>
    <div class="chi-datepicker__week-day">T</div>
    <div class="chi-datepicker__week-day">F</div>
    <div class="chi-datepicker__week-day">S</div>
  </div>
  <div class="chi-datepicker__days">
    <div class="chi-datepicker__day">1</div>
    <div class="chi-datepicker__day">2</div>
    <div class="chi-datepicker__day">3</div>
    <div class="chi-datepicker__day">4</div>
    <div class="chi-datepicker__day">5</div>
    <div class="chi-datepicker__day">6</div>
    <div class="chi-datepicker__day">7</div>
    <div class="chi-datepicker__day">8</div>
    <div class="chi-datepicker__day">9</div>
    <div class="chi-datepicker__day -active">10</div>
    <div class="chi-datepicker__day -active">11</div>
    <div class="chi-datepicker__day -active">12</div>
    <div class="chi-datepicker__day">13</div>
    <div class="chi-datepicker__day">14</div>
    <div class="chi-datepicker__day">15</div>
    <div class="chi-datepicker__day">16</div>
    <div class="chi-datepicker__day">17</div>
    <div class="chi-datepicker__day">18</div>
    <div class="chi-datepicker__day">19</div>
    <div class="chi-datepicker__day">20</div>
    <div class="chi-datepicker__day">21</div>
    <div class="chi-datepicker__day">22</div>
    <div class="chi-datepicker__day">23</div>
    <div class="chi-datepicker__day">24</div>
    <div class="chi-datepicker__day">25</div>
    <div class="chi-datepicker__day">26</div>
    <div class="chi-datepicker__day">27</div>
    <div class="chi-datepicker__day">28</div>
    <div class="chi-datepicker__day">29</div>
    <div class="chi-datepicker__day">30</div>
    <div class="chi-datepicker__day">31</div>
  </div>
</div>

Min and Max

<chi-date min="06/06/2024" max="06/22/2024"></chi-date>
This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.

Use class -inactive for deactivated dates.
<div class="chi-datepicker -week-starts-on-sun -month-starts-on-sat">
  <div class="chi-datepicker__month-row">
    <div class="prev -disabled"><i class="chi-icon icon-chevron-left -sm" aria-hidden="true"></i></div>
    <div class="chi-datepicker__month">June 2024</div>
    <div class="next -disabled"><i class="chi-icon icon-chevron-right -sm" aria-hidden="true"></i></div>
  </div>
  <div class="chi-datepicker__day-names">
    <div class="chi-datepicker__week-day">S</div>
    <div class="chi-datepicker__week-day">M</div>
    <div class="chi-datepicker__week-day">T</div>
    <div class="chi-datepicker__week-day">W</div>
    <div class="chi-datepicker__week-day">T</div>
    <div class="chi-datepicker__week-day">F</div>
    <div class="chi-datepicker__week-day">S</div>
  </div>
  <div class="chi-datepicker__days">
    <div class="chi-datepicker__day -inactive">1</div>
    <div class="chi-datepicker__day -inactive">2</div>
    <div class="chi-datepicker__day -inactive">3</div>
    <div class="chi-datepicker__day -inactive">4</div>
    <div class="chi-datepicker__day -inactive">5</div>
    <div class="chi-datepicker__day">6</div>
    <div class="chi-datepicker__day">7</div>
    <div class="chi-datepicker__day">8</div>
    <div class="chi-datepicker__day">9</div>
    <div class="chi-datepicker__day">10</div>
    <div class="chi-datepicker__day">11</div>
    <div class="chi-datepicker__day">12</div>
    <div class="chi-datepicker__day">13</div>
    <div class="chi-datepicker__day">14</div>
    <div class="chi-datepicker__day">15</div>
    <div class="chi-datepicker__day">16</div>
    <div class="chi-datepicker__day">17</div>
    <div class="chi-datepicker__day">18</div>
    <div class="chi-datepicker__day">19</div>
    <div class="chi-datepicker__day">20</div>
    <div class="chi-datepicker__day">21</div>
    <div class="chi-datepicker__day">22</div>
    <div class="chi-datepicker__day -inactive">23</div>
    <div class="chi-datepicker__day -inactive">24</div>
    <div class="chi-datepicker__day -inactive">25</div>
    <div class="chi-datepicker__day -inactive">26</div>
    <div class="chi-datepicker__day -inactive">27</div>
    <div class="chi-datepicker__day -inactive">28</div>
    <div class="chi-datepicker__day -inactive">29</div>
    <div class="chi-datepicker__day -inactive">30</div>
  </div>
</div>

Date and Time

November 2024
S
M
T
W
T
F
S
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
12
01
02
03
04
05
06
07
08
09
10
11
00
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
AM
PM
<chi-date></chi-date>
<chi-time></chi-time>

chi-date-picker

Properties

Property
Attribute
Description
Type
Default
active
active
Indicates whether the dropdown calendar is open or closed
boolean
false
disabled
disabled
to disable chi-date-picker.
boolean
false
displaySeconds
display-seconds
Displaying seconds column
boolean
false
excludedDates
excluded-dates
To specify which dates to disable
string
undefined
excludedWeekdays
excluded-weekdays
To specify which days of week to disable
string
undefined
format
format
Date format used in the attributes and how it will be shown to the user.
"DD-MM-YYYY" | "DD/MM/YYYY" | "MM-DD-YYYY" | "MM/DD/YYYY" | "YYYY-MM-DD" | "YYYY/MM/DD"
'MM/DD/YYYY'
helperMessage
helper-message
To display an additional helper text message below the Date Picker
string
undefined
locale
locale
Locale to use in date picker
"de" | "en" | "es" | "fr" | "ja" | "pt" | "zh"
'en'
max
max
Maximum eligible date
string
'12/31/2099'
min
min
Minimum eligible date
string
'01/01/1900'
minutesStep
minutes-step
Renders minutes in stepped format. Defaults to 15 min steps if no value is provided (see examples in docs).
1 | 10 | 15 | 20 | 30 | 5
15
mode
mode
To render Date Picker with Time Picker
string
'date'
multiple
multiple
To allow the user to select multiple dates
boolean
false
state
state
To define state color of Date Picker
"danger" | "success" | "warning"
undefined
timeFormat
time-format
To specify format for the Time Picker. Applicable only if mode is equal to 'datetime'
"12hr" | "24hr"
'12hr'
value
value
Selected date in the date picker
string
undefined

Events

Event
Description
Type
chiDateChange
Date change value event
CustomEvent<any>
chiDateInvalid
Triggered if the date value introduced by the user is invalid
CustomEvent<any>

Methods

Method
Description
Returns
Parameters
getDate() => Promise<string>
Gets date

Type: Promise<string>

-
resetDate() => Promise<void>
Resets date

Type: Promise<void>

-
setDate(date: any) => Promise<void>
Sets date

Type: Promise<void>

date:any

chi-date

Properties

Property
Attribute
Description
Type
Default
excludedDates
excluded-dates
To specify which dates to disable
string
undefined
excludedWeekdays
excluded-weekdays
To specify which days of week to disable
string
undefined
format
format
Date format used in the attributes and how it will be shown to the user.
"DD-MM-YYYY" | "DD/MM/YYYY" | "MM-DD-YYYY" | "MM/DD/YYYY" | "YYYY-MM-DD" | "YYYY/MM/DD"
'MM/DD/YYYY'
locale
locale
Locale to use in date picker
"de" | "en" | "es" | "fr" | "ja" | "pt" | "zh"
'en'
max
max
Maximum eligible date
string
'12/31/2099'
min
min
Minimum eligible date
string
'01/01/1900'
multiple
multiple
To allow the user to select multiple dates
boolean
false
value
value
Selected date in the date picker
string
undefined

Events

Event
Description
Type
chiDateChange
Date change value event
CustomEvent<any>

Methods

Method
Description
Returns
Parameters
getDate() => Promise<string>
Gets date

Type: Promise<string>

-
setDate(date: any) => Promise<void>
Sets date

Type: Promise<void>

date:any

JavaScript

This component accepts options to configure its behavior.

Option
Default
Description
date
null
Sets the initial date into the date picker. Overrides the value of the input.
locale
'en'
Sets the locale for names of months and days of the week. The locales supported are the ones supported by Day.js. Locales must be imported before using them. List of supported locales.
min
'01/01/1900'
Prevent user pick a date before the configured.
max
'12/31/2100'
Prevent user pick a date after the configured.
format
'MM/DD/YYYY'
Format of the date used in the input.

Accessibility

Keyboard Navigation

KeyFunction
TabMoves focus to next element in Tab sequence. If focus is on the pop-over, moves focus to the first chevron.
Shift + TabMoves focus to the previous focusable element.
Enter,SpaceSelects the option and closes the dropdown.
Up ArrowMoves focus to the same day of the previous week.
Down ArrowMoves focus to the same day of the next week.
Right ArrowMoves focus to the next day.
Left ArrowMoves focus to the previous day.
EscCloses the popup.

For comprehensive details on keyboard support, refer to our Keyboard Control Guide.

Visit WebAIM for keyboard techniques.

Guidance for developers
  • Keyboard Navigation: Support navigation through days, months, and years using arrow keys, and allow selection with the "Enter" key.
  • Use label elements to provide descriptive labels for each select component. Ensure the for attribute of the label matches the id of the select box to support screen readers.
  • Use appropriate ARIA roles and attributes to enhance accessibility. For example, role="listbox" for the select element and role="option" for each option.
  • Error Handling and Feedback: Provide clear and immediate feedback for actions such as selection errors. Use ARIA live regions to announce updates or errors dynamically.
  • Test compatibility with various screen readers (like JAWS, NVDA, or VoiceOver) to ensure the date picker component is announced correctly. Options should be clearly read out when navigated.
  • Implement visible focus styles to help keyboard users determine which element has focus.
Guidance for designers
  • Ensure all interactive elements in the date picker, like day selections and navigation buttons, meet the minimum target size of 44x44 pixels, as recommended by WCAG 2.5.5.
  • Design elements with adequate spacing to prevent accidental activations.
  • Design the date picker with high contrast between text and background colors, ensuring a minimum contrast ratio of 4.5:1 for text.
  • Employ distinct visual styles for error states using icons, text styles, and colors to clearly denote and explain errors like invalid dates or format issues.
  • Implement noticeable focus indicators on interactive elements, using enhanced borders, outlines, or shadows to clearly mark the active element during keyboard navigation.
  • Use spacing, typography, and visual cues effectively.
  • Maintain consistency in the design of the date picker to provide a cohesive user experience.

Find live examples in the W3 Date Picker Example.

Resources

Other recommendations

Explore additional accessibility tips in the general Accessibility Guide.

WCAG 2.2 Guidelines

  • Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose. (Level A)
  • Info and Relationships: Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)
  • Headings and Labels: Headings and labels describe topic or purpose. (Level AA)
  • Labels or Instructions: Labels or instructions are provided when content requires user input. (Level A)
  • Name, Role, Value: For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)