Date Picker

Examples

Single Example

<vega-date-picker 
    label="Single mode" 
    mode="single" 
    size="small" 
    format="MM/DD/YYYY"
    clear-button="true">
</vega-date-picker>

Range Example

<vega-date-picker 
    label="Range mode" 
    mode="range" 
    size="small" 
    format="MM/DD/YYYY"
    clear-button="true"
    allow-repick="true">
</vega-date-picker>

Range with Min and Max Date

<vega-date-picker
    id="minMaxSingleDatePicker"
    label="Min & Max Date Range"
    max-date="05/20/2022"
    min-date="05/10/2022"
    mode="range"
  />

Usage

The Date Picker component is a calendar which can appear on various date fields when a user needs to select a specific date for an event.

Date Picker components are used as variations on an input-field when a date selection is necessary. When a user interacts with the input field on a form, the Date Picker is displayed as a calendar popover.

There are two basic modes: single, which displays a single month, and range which will display two months side by side, where users can specify a start and end date with a single click.

Properties

Name	Description	Default
label	This will set the default label text for the date picker. string	""
mode	The mode of date picker. Accepted values are ‘single’ or ‘range’	single
size	The size of date picker. Can be ‘default’ pr ‘small’.	default
required	This is a Boolean operator which indicates whether the vega-date-picker is required. boolean	false
format	Sets the date format. string	MM/DD/YYYY
auto-validation	Boolean indicator for whether to automatically validate the user’s input.	true
form-validation	Updating the value of this property triggers the validation process. number	0
validation-rules	The array custom validation rule you would like to attach to the input. Format: `Array<{canEvaluate: (input: string) => boolean, evaluate: (input: string) => EvaluateResult}>`
value	This is a preset value for date picker. For single mode the value will be a `string`, for range mode the value will be an `array` includes start date and end date string, array
min-date	The minimum/earliest date that can be selected. string	""
max-date	The maximum/the latest date that can be selected. string	""
placeholder	The placeholder of date input. string \| string[]
clear-button	Whether to show clear button. Boolean	false
read-only	Set the readOnly attribute of the input tag (avoids virtual keyboard on touch devices). boolean	false
allow-repick	If the date range is already selected, a user can change either the start date or end date boolean	false
disabled	Provides option for disabling the date picker Boolean	false
Dropdown-config
positionRelativeTo	A selector element that contains the date picker. If the date picker exists within a scrolling container, you may set this property to ensure the date picker will not scroll with the container
staticHeight	The dropdown calendar will aligned using auto height if set to `false`. If set to `true` it will have a static height. Boolean	true

For more details view in Storybook

Accessibility

ARIA commands must have an accessible name
Required ARIA attributes must be provided
ARIA roles used must conform to valid values
Elements must have sufficient color contrast
id attribute value must be unique
Form field must not have multiple label elements
Form elements must have labels

Best Practices

When to use a calendar

A good place to use a calendar date picker is if the date to be chosen is within a month or two of the current date, and definitely less than a year.

Always highlight or indicate the current date, so users don’t need to look it up elsewhere.

If using a calendar for service scheduling, do not allow users to pick dates which are not available.

Always provide an alternative method for entering the date other than the calendar, particularly for keyboard-only users. This also means providing a clear indication of the correct format.

Only auto-trigger the calendar if it helps users save time.

In situations where a user is choosing a date, the current date is close to the end of a month, consider using the side-by-side two month layout, as is demonstrated in the date range picker version of the component.

When not to use a calendar

If the date is too far in the future or too far in the past (such as for a birth date), it can take users too long to scroll through the calendar to pick the correct date. Allow users to simply enter the date in a specified format.

Because of differences in the way that different countries and cultures numerically represent dates, when asking a user to input a date, provide the expected format (e.g. “MM/DD/YYYY”). This can be done with placeholder text or as a label. However, if using the placeholder approach, it is best if it does not immediately disappear as soon as the user starts typing, because it can be easy to forget the format.

When a user inputs a date, it is best to include the separators (either “/” or “-”) in the field, and have these automatically populate.