ba-input-datepicker
Airframe
Web Components
React
React Native
Anatomy
Label
Clearly identifies the purpose of the date field so users understand what date they are being asked to enter
Hint text
Optional supporting text that provides additional context or instructions to help users complete the field correctly
Input field
The native date input where the user enters or selects a date; its appearance and behaviour vary across browsers and devices
Calendar icon
A browser-native control that opens the datepicker popup; its presence and behaviour vary across browsers
Design Documentation
This component is best used where users are choosing from a relatively compact range of dates, where a visual datepicker is helpful.
For situations with a wider range of possibilities, e.g. date of birth or credit card expiry, consider using the ba-date-input component instead.
As this component uses the browser's native date input, the UX of the input field and its datepicker vary across browsers and devices.
For example:
- Chrome desktop has a button to open the datepicker, but doesn't open the datepicker automatically on click (like most other browsers)
- Firefox desktop has a 'clear' button inside the input
- Safari desktop has no button - clicking the input automatically opens the datepicker
Further reading:
As this component uses the browser's native date input, the format of the date value can vary based on browser and locale. Therefore you shouldn't refer to any particular format when instructing the user - e.g. Don't label it "Enter a date (dd/mm/yyyy)"
- US and UK device locales (for example) display the day and month in different orders
- Most browsers use a number format (01/01/2000) but iOS Safari shows the month in short word format (1 Jan 2000)
NB: The value accessed in code will be an empty string unless a valid date is entered, then value will always be in ISO format, regardless of the visual display format.
Further reading:
Live Demo
<ba-input-datepicker
label="Outbound date"
hint-text="Here's some help with this field"
value="2023-10-01"
name="date"
></ba-input-datepicker>
Properties and attributes
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
hintText |
hint-text |
Hint text for the input | string | undefined |
undefined |
invalid |
invalid |
If true then the error will be displayed. | boolean | undefined |
false |
label(required) |
label |
Label for the input. | string |
undefined |
max |
max |
Optional max date value in yyyy-mm-dd format | string | undefined |
this.getMaxDate() |
min |
min |
Optional min date value in yyyy-mm-dd format | string | undefined |
this.currentDate |
name(required) |
name |
The name of the input | string |
undefined |
required |
required |
If the field is required | boolean | undefined |
false |
value |
value |
The value of the input. | null | string | undefined |
'' |
Permitted ARIA roles
- None
Slots
| Slot | Description | Permitted elements |
|---|---|---|
"error" |
Text to show in an error message | <p> |
"minError" |
Text to show in an minError message | <p> |
"maxError" |
Text to show in an maxError message | <p> |
Parent components
ba-input-datepicker can be slotted into:
<ba‑grid><ba‑form‑group‑dropdown><ba‑form‑group><ba‑form><ba‑flex><ba‑details><ba‑card‑segmented><ba‑card><ba‑accordion>
Events
| Event | Description | Type |
|---|---|---|
baBlur |
Emitted when the input loses focus. | CustomEvent<void> |
baChange |
Emitted when the value has changed. | CustomEvent<InputDatepickerChangeEventDetail> |
baFocus |
Emitted when the input has focus. | CustomEvent<void> |
baSubmit |
Emitted when the input get submitted | CustomEvent<void> |
Usage
Basic usage
<ba-input-datepicker label="Outbound date" hint-text="Here's some help with this field"><p slot="error">Enter a valid date.</p></ba-input-datepicker>The value will be an empty string unless a valid date is entered, then value will always be in ISO format, regardless of the visual display format.
Setting min and max dates
The min and/or max attributes of the native date input can be set using the min and max attributes on the bagel component (in ISO format):
<ba-input-datepicker hint-text="Here's some help with this field" min="2022-07-30" max="2023-07-30" label="Outbound date"></ba-input-datepicker>On supporting browsers, these values restrict the range of dates that the user is able to select/input.
Guidelines
Always use the label attribute to give a meaningful label to the field.
Further reading:
Disabled form elements are not supported in BAgel because they create accessibility challenges, such as preventing keyboard navigation, confusing screen reader users, and reducing visual clarity for those with impairments
Further reading:
Keyboard navigation
State: Previous element in DOM has focus
The date input gets focus
State: Date input has focus
Next tabbable element gets focus
Usage and accessibility checklist
Use this checklist to confirm the component has been configured and used correctly.
UX checklist
- Use ba-input-datepicker for compact date ranges where a visual datepicker is helpful, such as selecting a travel date
- For wider date ranges such as date of birth or credit card expiry, use ba-date-input instead
- Do not reference a specific date format in the label or hint text, as the display format varies by browser and locale
- The component renders consistently across supported browsers, accounting for native differences
Accessibility checklist
- The input has a visible and descriptive label
- Hint text is programmatically associated with the input
- Error messages are visible and associated with the input
- The disabled state is communicated to assistive technology
- Focus indicator has not been obscured on all sides of the component
These checks are handled by the component and do not need to be repeated each time it is used.
- ba-input-datepicker is operable using assistive technology
- Has a visible focus indicator on all sides of the component
- Colour contrast for all states in all BAgel themes
- High contrast mode adjustments