Month Picker
AlphaJan | Feb | Mar | Apr |
May | Jun | Jul | Aug |
Sep | Oct | Nov | Dec |
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date';
import { MonthPickerCell, MonthPickerCellTrigger, MonthPickerGrid, MonthPickerGridBody, MonthPickerGridRow, MonthPickerHeader, MonthPickerHeading, MonthPickerNext, MonthPickerPrev, MonthPickerRoot } from 'akar';
import './styles.css';
const date = new CalendarDate(2024, 10, 1);
</script>
<template>
<div class="akar-demo akar-demo-MonthPicker">
<MonthPickerRoot
v-slot="{ grid }"
:default-value="date"
class="MonthPicker"
>
<MonthPickerHeader class="MonthPickerHeader">
<MonthPickerPrev class="MonthPickerNavButton">
<PIcon
name="i-lucide-chevron-left"
class="Icon"
/>
</MonthPickerPrev>
<MonthPickerHeading class="MonthPickerHeading" />
<MonthPickerNext class="MonthPickerNavButton">
<PIcon
name="i-lucide-chevron-right"
class="Icon"
/>
</MonthPickerNext>
</MonthPickerHeader>
<div class="MonthPickerWrapper">
<MonthPickerGrid class="MonthPickerGrid">
<MonthPickerGridBody class="MonthPickerGridWrapper">
<MonthPickerGridRow
v-for="(months, index) in grid.rows"
:key="`month-${index}`"
class="MonthPickerGridRow"
>
<MonthPickerCell
v-for="month in months"
:key="month.toString()"
:date="month"
class="MonthPickerCell"
>
<MonthPickerCellTrigger
:month="month"
class="MonthPickerCellTrigger"
/>
</MonthPickerCell>
</MonthPickerGridRow>
</MonthPickerGridBody>
</MonthPickerGrid>
</div>
</MonthPickerRoot>
</div>
</template>@import '../_colors/black-alpha.css';
@import '../_colors/grass.css';
@scope (.akar-demo-MonthPicker) {
.Icon {
width: 1rem;
height: 1rem;
}
.MonthPicker {
margin-top: 1.5rem;
border-radius: 0.75rem;
border: 1px solid #e5e5e5;
background-color: #ffffff;
box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
padding: 1rem;
}
.MonthPickerHeader {
display: flex;
justify-content: space-between;
align-items: center;
}
.MonthPickerNavButton {
display: inline-flex;
justify-content: center;
align-items: center;
width: 2rem;
height: 2rem;
color: #000000;
background-color: transparent;
cursor: pointer;
border-radius: 0.375rem;
}
.MonthPickerNavButton:hover {
background-color: #fafaf9;
}
.MonthPickerNavButton:focus {
box-shadow: 0 0 0 2px #000000;
}
.MonthPickerHeading {
font-size: 0.875rem;
font-weight: 500;
color: #000000;
}
.MonthPickerWrapper {
padding-top: 1rem;
}
.MonthPickerGrid {
width: 100%;
user-select: none;
}
.MonthPickerGridWrapper {
display: grid;
gap: 0.25rem 0;
}
.MonthPickerGridRow {
display: grid;
grid-template-columns: repeat(4, minmax(0, 1fr));
gap: 0.25rem;
}
.MonthPickerCell {
position: relative;
text-align: center;
}
.MonthPickerCellTrigger {
position: relative;
display: flex;
justify-content: center;
align-items: center;
width: 3rem;
height: 3rem;
border-radius: 0.5rem;
font-size: 0.875rem;
font-weight: 400;
color: #000000;
background-color: transparent;
outline: none;
cursor: pointer;
border: none;
}
.MonthPickerCellTrigger:hover {
background-color: var(--grass-5);
}
.MonthPickerCellTrigger:focus {
box-shadow: 0 0 0 2px #000000;
}
.MonthPickerCellTrigger[data-disabled] {
color: rgba(0, 0, 0, 0.3);
pointer-events: none;
}
.MonthPickerCellTrigger[data-selected] {
background-color: var(--grass-10);
color: #ffffff;
font-weight: 500;
}
.MonthPickerCellTrigger[data-unavailable] {
color: rgba(0, 0, 0, 0.3);
text-decoration: line-through;
pointer-events: none;
}
.MonthPickerCellTrigger::before {
content: '';
position: absolute;
top: 0.25rem;
width: 0.25rem;
height: 0.25rem;
border-radius: 9999px;
display: none;
}
.MonthPickerCellTrigger[data-today]::before {
display: block;
background-color: var(--grass-9);
}
.MonthPickerCellTrigger[data-selected]::before {
background-color: #ffffff;
}
}Features
- Full keyboard navigation
- Can be controlled or uncontrolled
- Focus is fully managed
- Localization support
- Highly composable
Preface
The component depends on the @internationalized/date package, which solves a lot of the problems that come with working with dates and times in JavaScript.
We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components.
Installation
Install the date package.
pnpm add @internationalized/date
yarn add @internationalized/date
npm install @internationalized/date
bun add @internationalized/date
Install the component from your command line.
pnpm add akar
yarn add akar
npm install akar
bun add akar
Anatomy
Import all parts and piece them together.
<script setup>
import {
MonthPickerCell,
MonthPickerCellTrigger,
MonthPickerGrid,
MonthPickerGridBody,
MonthPickerGridRow,
MonthPickerHeader,
MonthPickerHeading,
MonthPickerNext,
MonthPickerPrev,
MonthPickerRoot,
} from 'akar';
</script>
<template>
<MonthPickerRoot>
<MonthPickerHeader>
<MonthPickerPrev />
<MonthPickerHeading />
<MonthPickerNext />
</MonthPickerHeader>
<MonthPickerGrid>
<MonthPickerGridBody>
<MonthPickerGridRow>
<MonthPickerCell>
<MonthPickerCellTrigger />
</MonthPickerCell>
</MonthPickerGridRow>
</MonthPickerGridBody>
</MonthPickerGrid>
</MonthPickerRoot>
</template>
API Reference
Root
Contains all the parts of a month picker
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
calendarLabel | stringThe accessible label for the month picker | |
defaultPlaceholder | DateValueThe default placeholder date | |
defaultValue | DateValueThe default value for the month picker | |
dir | "ltr" | "rtl"The reading direction of the calendar when applicable. If omitted, inherits globally from | |
disabled | false | booleanWhether the month picker is disabled |
initialFocus | false | booleanIf true, the month picker will focus the selected month, today, or the first month of the year on mount |
isMonthDisabled | MatcherA function that returns whether or not a month is disabled | |
isMonthUnavailable | MatcherA function that returns whether or not a month is unavailable | |
locale | stringThe locale to use for formatting dates | |
maxValue | DateValueThe maximum date that can be selected | |
minValue | DateValueThe minimum date that can be selected | |
modelValue | DateValue | DateValue[] | nullThe controlled selected month value of the month picker. Can be bound as | |
multiple | false | booleanWhether multiple months can be selected |
nextPage | ((placeholder: DateValue) => DateValue)A function that returns the next page of the month picker. Receives the current placeholder as an argument. | |
placeholder | DateValueThe placeholder date, which is used to determine what year to display when no date is selected | |
preventDeselect | false | booleanWhether or not to prevent the user from deselecting a date without selecting another date first |
prevPage | ((placeholder: DateValue) => DateValue)A function that returns the previous page of the month picker. Receives the current placeholder as an argument. | |
readonly | false | booleanWhether the month picker is readonly |
| Event | Payload |
|---|---|
update:modelValue | date: DateValue | DateValue[]Event handler called whenever the model value changes |
update:placeholder | date: DateValueEvent handler called whenever the placeholder value changes |
| Slot (default) | Payload |
|---|---|
date | DateValueThe current date of the placeholder |
grid | Grid<DateValue>The grid of months |
locale | stringThe month picker locale |
modelValue | DateValue | DateValue[]The current selected value |
| Data attribute | Value |
|---|---|
[data-readonly] | Present when readonly |
[data-disabled] | Present when disabled |
[data-invalid] | Present when invalid |
Header
Contains the navigation buttons and the heading segments.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. |
Prev Button
Calendar navigation button. It navigates the calendar one year in the past.
| Prop | Default | Type |
|---|---|---|
as | "button" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
prevPage | ((placeholder: DateValue) => DateValue)The function to be used for the prev page. Overwrites the |
| Slot (default) | Payload |
|---|---|
disabled | booleanCurrent disable state |
| Data attribute | Value |
|---|---|
[data-disabled] | Present when disabled |
Next Button
Calendar navigation button. It navigates the calendar one year in the future.
| Prop | Default | Type |
|---|---|---|
as | "button" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
nextPage | ((placeholder: DateValue) => DateValue)The function to be used for the next page. Overwrites the |
| Slot (default) | Payload |
|---|---|
disabled | booleanCurrent disable state |
| Data attribute | Value |
|---|---|
[data-disabled] | Present when disabled |
Heading
Heading for displaying the current year.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. |
| Slot (default) | Payload |
|---|---|
headingValue | stringCurrent year heading |
| Data attribute | Value |
|---|---|
[data-disabled] | Present when disabled |
Grid
Container for wrapping the month picker grid.
| Prop | Default | Type |
|---|---|---|
as | "table" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. |
| Data attribute | Value |
|---|---|
[data-readonly] | Present when readonly |
[data-disabled] | Present when disabled |
Grid Body
Container for wrapping the grid body.
| Prop | Default | Type |
|---|---|---|
as | "tbody" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. |
Grid Row
Container for wrapping the grid row.
| Prop | Default | Type |
|---|---|---|
as | "tr" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. |
Cell
Container for wrapping the month picker cells.
| Prop | Default | Type |
|---|---|---|
as | "td" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
date* | DateValueThe date value for the cell |
| Data attribute | Value |
|---|---|
[data-disabled] | Present when disabled |
Cell Trigger
Interactable container for displaying the cell months. Clicking it selects the month.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
month* | DateValueThe date value provided to the cell trigger |
| Slot (default) | Payload |
|---|---|
monthValue | stringCurrent month value (short name) |
disabled | booleanCurrent disable state |
selected | booleanCurrent selected state |
today | booleanCurrent month/year is today state |
unavailable | booleanCurrent unavailable state |
| Data attribute | Value |
|---|---|
[data-selected] | Present when selected |
[data-value] | The ISO string value of the date. |
[data-disabled] | Present when disabled |
[data-unavailable] | Present when unavailable |
[data-today] | Present when the month is the current month |
[data-focused] | Present when focused |
Accessibility
Keyboard Interactions
| Key | Description |
|---|---|
| Tab | When focus moves onto the month picker, focuses the first navigation button. |
| Space | When the focus is on either MonthPickerNext or MonthPickerPrev, it navigates the calendar. Otherwise, it selects the month. |
| Enter | When the focus is on either MonthPickerNext or MonthPickerPrev, it navigates the calendar. Otherwise, it selects the month. |
| ArrowLeft/ArrowRight/ArrowUp/ArrowDown | When the focus is on MonthPickerCellTrigger, it navigates the months, changing the year if necessary. |
| PageUp | When the focus is on MonthPickerCellTrigger, it navigates to the same month in the previous year. |
| PageDown | When the focus is on MonthPickerCellTrigger, it navigates to the same month in the next year. |