MonthPicker
Usage
Allow deselect
Set allowDeselect
to allow user to deselect current selected date by clicking on it.
allowDeselect
is disregarded when type
prop is range
or multiple
. When date is
deselected onChange
is called with null
.
Multiple dates
Set type="multiple"
to allow user to pick multiple dates:
Dates range
Set type="range"
to allow user to pick dates range:
Single date in range
By default, it is not allowed to select single date as range – when user clicks the same date second time it is deselected.
To change this behavior set allowSingleDateInRange
prop. allowSingleDateInRange
is ignored when
type
prop is not range
.
Default date
Use defaultDate
prop to set date value that will be used to determine which year should be displayed initially.
For example to display 2015
year set defaultDate={new Date(2015, 1)}
. If value is not specified,
then defaultDate
will use new Date()
. Month, day, minutes and seconds are ignored in provided date object, only year is used –
you can specify any date value.
Note that if you set date
prop, then defaultDate
value will be ignored.
Controlled date
Set date
, and onDateChange
props to make currently displayed year and decade controlled.
By doing so, you can customize date picking experience, for example, when user selects first date in range,
you can add one year to current date value:
Min and max date
Set minDate
and maxDate
props to define min and max dates. If previous/next page is not available
then corresponding control will be disabled.
Add props to year and month control
You can add props to year and month controls with getYearControlProps
and getMonthControlProps
functions. Both functions accept date as single argument,
props returned from the function will be added to year/month control. For example, it can be used to disable specific
control or add styles:
Number of columns
Set numberOfColumns
prop to define number of pickers that will be rendered side by side:
Max level
To disallow user going to the decade level set maxLevel="year"
:
Size
Change year and months controls format
Use yearsListFormat
and monthsListFormat
props to change dayjs format of year/month controls:
Change label format
Use decadeLabelFormat
and yearLabelFormat
to change dayjs format of decade/year label:
Localization
Usually it is better to specify @asuikit/dates
package locale in DatesProvider,
but you can also override locale per component:
Accessibility
Aria labels
Set ariaLabels
prop to specify aria-label
attributes for next/previous controls:
Year/month control aria-label
Use getYearControlProps
/getMonthControlProps
to customize aria-label
attribute:
Keyboard interactions
Note that the following events will only trigger if focus is on month control.
Key | Description |
---|---|
ArrowRight | Focuses next non-disabled month |
ArrowLeft | Focuses previous non-disabled month |
ArrowDown | Focuses next non-disabled month in the same column |
ArrowUp | Focuses previous non-disabled month in the same column |
MonthPicker component props
Name | Type | Description |
---|---|---|
allowDeselect | boolean | Determines whether user can deselect the date by clicking on selected item, applicable only when type="default" |
allowSingleDateInRange | boolean | Determines whether single year can be selected as range, applicable only when type="range" |
ariaLabels | CalendarAriaLabels | aria-label attributes for controls on different levels |
columnsToScroll | number | Number of columns to scroll when user clicks next/prev buttons, defaults to numberOfColumns |
date | Date | Date that is displayed, used for controlled component |
decadeLabelFormat | string | ((startOfDecade: Date, endOfDecade: Date) => ReactNode) | dayjs label format to display decade label or a function that returns decade label based on date value, defaults to "YYYY" |
defaultDate | Date | Initial date that is displayed, used for uncontrolled component |
defaultLevel | "year" | "decade" | Initial level displayed to the user (decade, year, month), used for uncontrolled component |
defaultValue | Date | DatesRangeValue | Date[] | Default value for uncontrolled component |
getMonthControlProps | (date: Date) => Partial<PickerControlProps> | Adds props to month picker control based on date |
getYearControlProps | (date: Date) => Partial<PickerControlProps> | Adds props to year picker control based on date |
level | "year" | "decade" | Current level displayed to the user (decade, year, month), used for controlled component |
locale | string | dayjs locale, defaults to value defined in DatesProvider |
maxDate | Date | Maximum possible date |
maxLevel | "year" | "decade" | Max level that user can go up to (decade, year), defaults to decade |
minDate | Date | Minimum possible date |
monthsListFormat | string | dayjs format for months list |
numberOfColumns | number | Number of columns to render next to each other |
onChange | (value: DatePickerValue<Type>) => void | Called when value changes |
onDateChange | (date: Date) => void | Called when date changes |
onLevelChange | (level: MonthPickerLevel) => void | Called when level changes |
onNextDecade | (date: Date) => void | Called when next decade button is clicked |
onNextYear | (date: Date) => void | Called when next year button is clicked |
onPreviousDecade | (date: Date) => void | Called when previous decade button is clicked |
onPreviousYear | (date: Date) => void | Called when previous year button is clicked |
size | "xs" | "sm" | "md" | "lg" | "xl" | Component size |
type | "default" | "multiple" | "range" | Picker type: range, multiple or default |
value | Date | DatesRangeValue | Date[] | Value for controlled component |
withCellSpacing | boolean | Determines whether controls should be separated by spacing, true by default |
yearLabelFormat | string | ((year: Date) => ReactNode) | dayjs label format to display year label or a function that returns year label based on year value, defaults to "YYYY" |
yearsListFormat | string | dayjs format for years list |
MonthPicker component Styles API
Name | Static selector | Description |
---|---|---|
calendar | .asuikit-MonthPicker-calendar | Calendar root element |
calendarHeader | .asuikit-MonthPicker-calendarHeader | Calendar header root element |
calendarHeaderControl | .asuikit-MonthPicker-calendarHeaderControl | Previous/next calendar header controls |
calendarHeaderControlIcon | .asuikit-MonthPicker-calendarHeaderControlIcon | Icon of previous/next calendar header controls |
calendarHeaderLevel | .asuikit-MonthPicker-calendarHeaderLevel | Level control (changes levels when clicked, month -> year -> decade) |
decadeLevelGroup | .asuikit-MonthPicker-decadeLevelGroup | Group of decades levels |
decadeLevel | .asuikit-MonthPicker-decadeLevel | Decade level root element |
pickerControl | .asuikit-MonthPicker-pickerControl | Button used to pick months and years |
yearsList | .asuikit-MonthPicker-yearsList | Years list table element |
yearsListRow | .asuikit-MonthPicker-yearsListRow | Years list row element |
yearsListCell | .asuikit-MonthPicker-yearsListCell | Years list cell element |
yearLevelGroup | .asuikit-MonthPicker-yearLevelGroup | Group of year levels |
yearLevel | .asuikit-MonthPicker-yearLevel | Year level root element |
monthsList | .asuikit-MonthPicker-monthsList | Months list table element |
monthsListRow | .asuikit-MonthPicker-monthsListRow | Months list table row element |
monthsListCell | .asuikit-MonthPicker-monthsListCell | Months list table cell element |