Month Range Picker
AlphaJan | Feb | Mar | Apr |
May | Jun | Jul | Aug |
Sep | Oct | Nov | Dec |
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date';
import { MonthRangePickerCell, MonthRangePickerCellTrigger, MonthRangePickerGrid, MonthRangePickerGridBody, MonthRangePickerGridRow, MonthRangePickerHeader, MonthRangePickerHeading, MonthRangePickerNext, MonthRangePickerPrev, MonthRangePickerRoot } from 'akar';
import './styles.css';
const defaultValue = {
start: new CalendarDate(2024, 3, 1),
end: new CalendarDate(2024, 6, 1),
};
</script>
<template>
<div class="akar-demo akar-demo-MonthRangePicker">
<MonthRangePickerRoot
v-slot="{ grid }"
:default-value="defaultValue"
class="MonthRangePicker"
>
<MonthRangePickerHeader class="MonthRangePickerHeader">
<MonthRangePickerPrev class="MonthRangePickerNavButton">
<PIcon
name="i-lucide-chevron-left"
class="Icon"
/>
</MonthRangePickerPrev>
<MonthRangePickerHeading class="MonthRangePickerHeading" />
<MonthRangePickerNext class="MonthRangePickerNavButton">
<PIcon
name="i-lucide-chevron-right"
class="Icon"
/>
</MonthRangePickerNext>
</MonthRangePickerHeader>
<div class="MonthRangePickerWrapper">
<MonthRangePickerGrid class="MonthRangePickerGrid">
<MonthRangePickerGridBody class="MonthRangePickerGridWrapper">
<MonthRangePickerGridRow
v-for="(months, index) in grid.rows"
:key="`month-${index}`"
class="MonthRangePickerGridRow"
>
<MonthRangePickerCell
v-for="month in months"
:key="month.toString()"
:date="month"
class="MonthRangePickerCell"
>
<MonthRangePickerCellTrigger
:month="month"
class="MonthRangePickerCellTrigger"
/>
</MonthRangePickerCell>
</MonthRangePickerGridRow>
</MonthRangePickerGridBody>
</MonthRangePickerGrid>
</div>
</MonthRangePickerRoot>
</div>
</template>@import '../_colors/black-alpha.css';
@import '../_colors/grass.css';
@scope (.akar-demo-MonthRangePicker) {
.Icon {
width: 1rem;
height: 1rem;
}
.MonthRangePicker {
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;
}
.MonthRangePickerHeader {
display: flex;
justify-content: space-between;
align-items: center;
}
.MonthRangePickerNavButton {
display: inline-flex;
justify-content: center;
align-items: center;
width: 2rem;
height: 2rem;
color: #000000;
background-color: transparent;
cursor: pointer;
border-radius: 0.375rem;
}
.MonthRangePickerNavButton:hover {
background-color: #fafaf9;
}
.MonthRangePickerNavButton:focus {
box-shadow: 0 0 0 2px #000000;
}
.MonthRangePickerHeading {
font-size: 0.875rem;
font-weight: 500;
color: #000000;
}
.MonthRangePickerWrapper {
padding-top: 1rem;
}
.MonthRangePickerGrid {
width: 100%;
user-select: none;
}
.MonthRangePickerGridWrapper {
display: grid;
gap: 0.25rem 0;
}
.MonthRangePickerGridRow {
display: grid;
grid-template-columns: repeat(4, minmax(0, 1fr));
gap: 0.25rem;
}
.MonthRangePickerCell {
position: relative;
text-align: center;
}
.MonthRangePickerCellTrigger {
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;
}
.MonthRangePickerCellTrigger:hover {
background-color: var(--grass-5);
}
.MonthRangePickerCellTrigger:focus {
box-shadow: 0 0 0 2px #000000;
}
.MonthRangePickerCellTrigger[data-disabled] {
color: rgba(0, 0, 0, 0.3);
pointer-events: none;
}
.MonthRangePickerCellTrigger[data-selected] {
background-color: var(--grass-10);
color: #ffffff;
font-weight: 500;
}
.MonthRangePickerCellTrigger[data-highlighted] {
background-color: var(--grass-5);
}
.MonthRangePickerCellTrigger[data-unavailable] {
color: rgba(0, 0, 0, 0.3);
text-decoration: line-through;
pointer-events: none;
}
.MonthRangePickerCellTrigger::before {
content: '';
position: absolute;
top: 0.25rem;
width: 0.25rem;
height: 0.25rem;
border-radius: 9999px;
display: none;
}
.MonthRangePickerCellTrigger[data-today]::before {
display: block;
background-color: var(--grass-9);
}
.MonthRangePickerCellTrigger[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 {
MonthRangePickerCell,
MonthRangePickerCellTrigger,
MonthRangePickerGrid,
MonthRangePickerGridBody,
MonthRangePickerGridRow,
MonthRangePickerHeader,
MonthRangePickerHeading,
MonthRangePickerNext,
MonthRangePickerPrev,
MonthRangePickerRoot,
} from 'akar';
</script>
<template>
<MonthRangePickerRoot>
<MonthRangePickerHeader>
<MonthRangePickerPrev />
<MonthRangePickerHeading />
<MonthRangePickerNext />
</MonthRangePickerHeader>
<MonthRangePickerGrid>
<MonthRangePickerGridBody>
<MonthRangePickerGridRow>
<MonthRangePickerCell>
<MonthRangePickerCellTrigger />
</MonthRangePickerCell>
</MonthRangePickerGridRow>
</MonthRangePickerGridBody>
</MonthRangePickerGrid>
</MonthRangePickerRoot>
</template>
API Reference
Root
Contains all the parts of a month range picker
| Prop | Default | Type |
|---|---|---|
allowNonContiguousRanges | false | booleanWhen combined with |
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 calendar | |
defaultPlaceholder | DateValueThe default placeholder date | |
defaultValue | { start: undefined, end: undefined } | DateRangeThe default value for the calendar |
dir | "ltr" | "rtl"The reading direction of the calendar when applicable. | |
disabled | false | booleanWhether or not the calendar is disabled |
fixedDate | "start" | "end"Which part of the range should be fixed | |
initialFocus | false | booleanIf true, the calendar will focus the selected month 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 | |
maximumMonths | numberThe maximum number of months that can be selected in a range | |
maxValue | DateValueThe maximum date that can be selected | |
minValue | DateValueThe minimum date that can be selected | |
modelValue | DateRange | nullThe controlled selected month range of the month range picker. Can be bound as | |
nextPage | ((placeholder: DateValue) => DateValue)A function that returns the next page of the calendar. | |
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 calendar. | |
readonly | false | booleanWhether or not the calendar is readonly |
| Event | Payload |
|---|---|
update:modelValue | date: DateRangeEvent handler called whenever the model value changes |
update:placeholder | date: DateValueEvent handler called whenever the placeholder value changes |
update:startValue | date: DateValueEvent handler called whenever the start value changes |
| Slot (default) | Payload |
|---|---|
date | DateValueThe current date of the placeholder |
grid | Grid<DateValue>The grid of months |
locale | stringThe calendar locale |
modelValue | DateRangeThe current date range |
| 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 range 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 range 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 is today's month state |
unavailable | booleanCurrent unavailable state |
highlighted | booleanCurrent highlighted state |
highlightedStart | booleanCurrent highlighted start state |
highlightedEnd | booleanCurrent highlighted end state |
selectionStart | booleanCurrent selection start state |
selectionEnd | booleanCurrent selection end 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-selection-start] | Present when the month is the start of the selection. |
[data-selection-end] | Present when the month is the end of the selection. |
[data-highlighted] | Present when the month is highlighted by the user as they select a range. |
[data-highlighted-start] | Present when the month is the start of the range that is highlighted by the user. |
[data-highlighted-end] | Present when the month is the end of the range that is highlighted by the user. |
[data-focused] | Present when focused |
Accessibility
Keyboard Interactions
| Key | Description |
|---|---|
| Tab | When focus moves onto the month range picker, focuses the first navigation button. |
| Space | When the focus is on either MonthRangePickerNext or MonthRangePickerPrev, it navigates the calendar. Otherwise, it selects the month. |
| Enter | When the focus is on either MonthRangePickerNext or MonthRangePickerPrev, it navigates the calendar. Otherwise, it selects the month. |
| ArrowLeft/ArrowRight/ArrowUp/ArrowDown | When the focus is on MonthRangePickerCellTrigger, it navigates the months, changing the year if necessary. |
| PageUp | When the focus is on MonthRangePickerCellTrigger, it navigates to the same month in the previous year. |
| PageDown | When the focus is on MonthRangePickerCellTrigger, it navigates to the same month in the next year. |
| Escape | Cancels the current range selection and restores the previous valid range. |