@asphalt-react/date-picker

DatePicker

DatePicker lets the user pick a single date via a popover calendar or type a date in the date textfield. The format — which is also the placeholder - should be ISO-8601 YYYY-MM-DD. Clicking the button in the date field toggles the calendar.

The calendar contains 2 sections:

• The top section contains buttons to navigate to adjacent months and toggle the year panel. The user can choose a year from the year panel.

• The bottom section displays the dates. First day of the week is configurable. The non-working days — which are configurable — appear in a different color. DatePicker supports i18n via the locale prop.

To set range, use the minDate & maxDate props. There are 3 variants offering different date ranges:

1. pro: Default variant which shows dates from 10 years before the current year or the initial date's year to 10 years ahead
2. dob: Shows dates in the past from 85 years to 13 years prior to current year. Additionally, the non-working days are not marked.
3. event: Shows dates from today's date or initial date to 6 months ahead

In touch supported devices it renders a native date picker. If the browser doesn't support <input type="date" />, then it does not.

Usage

import DatePicker from "@asphalt-react/date-picker"

function App() {
  const [date, setDate] = React.useState(null)

  return (
    <DatePicker value={date} onDateChange={({ date, event }) => setDate(date)}>
  )
}

Errors

Dates are complex objects to deal with and can easily cause issues. DatePicker checks for various issues which may arise during interaction. Detects & notifies these errors:

1. InvalidDate: When an invalid date is passed. Use the new Date() constructor to create date objects.
2. InvalidRange: When the minDate is ahead of maxDate.
3. RangeBreach: When the date falls outside of the selectable range.
4. UserInvalidDate: When the user types an invalid date or the date does not match the required format. For example:
   • 2020-12-25 ✅
   • 2019-2-10 ✅
   • lorem ipsum ❌ - invalid date
   • 2019-12-45 ❌ - invalid date
   • 25/12/2020 ❌ - incorrect format
5. UserRangeBreach: When the user enters a date which falls outside of the selectable range

Accessibility

DatePicker works well with assistive technologies. You can enable certain features via props.

The default focus lands on the date tile containing the selected date (if provided) or today's date. DatePicker traps & rotates focus among actionable elements.

Keyboard shortcuts

You can navigate & select using these keyboard shortcuts:

• Use ←, →, ↑ and ↓ to navigate among the dates
• Use space or enter to select a date
• Use option ( alt for windows ) + ← or → to navigate to the same date of the adjacent month
• Use meta + ← or → to navigate to the same month of the adjacent year
• Use tab or shift + tab to rotate focus in the calendar and in the year panel
• Use esc to close the year panel
• Use esc to close the calendar

Data attributes

DatePicker accepts data-* attributes and passes it to the date field.

Props

value

Selected date. Pass null or undefined to set today's date

Note: DatePicker will show the console warnings if value or onDateChange props are missing, as they are needed to update the date. Hence, we recommend you to pass both the props.

type	required	default
object	false	N/A

onDateChange

Callback called when date is either:

1. selected from the calendar
2. typed in the date field

The argument is of the shape:

• date: Date instance of selected date
• event: React's synthetic event

funtion onDateChange({ date, event }) {}

Note: DatePicker will show the console warnings if value or onDateChange props are missing, as they are needed to update the date. Hence, we recommend you to pass both the props.

type	required	default
func	false	N/A

minDate

Minimum selectable date (inclusive)

type	required	default
object	false	N/A

maxDate

Maximum selectable date (inclusive)

type	required	default
object	false	N/A

locale

The language locale to format days and months. It also determines the first day of the week. DatePicker provides a set of pre-defined locale codes:

• "en-US" - English (United States)
• "en-IN" - English (India)
• "id" - Bahasa (Indonesia)
• "vi" - Vietnamese
• "th" - Thai

You can pass other locales as an object. Checkout date-fns for the available locales.

type	required	default
union	false	"en-US"

weekStartsOn

Override first day of the week of a locale. As the default locale is ‘en-US', the week starts on Sunday by default

The value should be one of "sun", "mon", "tue", "wed", "thu", "fri", "sat"

type	required	default
enum	false	N/A

nonWorkingDays

The non working days (weekends) for a week.

The value can be any combination of "sun", "mon", "tue", "wed", "thu", "fri", "sat"

type	required	default
arrayOf	false	["sat", "sun"]

invalid

Renders DatePicker in error state

type	required	default
bool	false	N/A

onError

Callback called when an error occurs. The argument is an instance of JS Error

funtion onError(error) {}

type	required	default
func	false	N/A

pro

Renders pro variant.

type	required	default
bool	false	N/A

dob

Renders dob variant

type	required	default
bool	false	N/A

event

Renders event variant

type	required	default
bool	false	N/A

size

Size of the DatePicker. Available values are "m" and "l"

type	required	default
enum	false	"m"

placeholder

Placeholder for date field

type	required	default
string	false	"yyyy-mm-dd"

stretch

Enables date field to take parent's width.

The size of the calendar does not change

type	required	default
bool	false	false

disabled

Disables the DatePicker

type	required	default
bool	false	false

calendarId

ID to uniquely identify the calendar.

For accessibility

type	required	default
string	false	N/A

calendarLabel

Override the aria-label of the calendar toggle button. The label should have values for 2 cases:

1. If no date selected - the label should ask the user to select a date
2. If date is selected - the label should also mention the selected date along with case 1

For accessibility

type	required	default
string	false	N/A

nextMonthLabel

Override aria-label for the button to navigate to next month

For accessibility

type	required	default
string	false	N/A

previousMonthLabel

Override aria-label for the button to navigate to previous month

For accessibility

type	required	default
string	false	N/A