Calendar

A Jetpack Compose calendar component. Supports single date selection, date range selection, date restriction modes, month/year picker dialogs, and full color customization.

Calendar renders a month grid with navigation arrows, clickable month/year selector chips, and a day grid. It comes in two flavors of the primary composable — a convenience overload for single-date selection and a selectionMode-based overload that additionally supports range selection.

Basic Usage

The simplest way to use the calendar is through the single-date convenience overload. Pass selectedDate and an onDateSelected callback.

Single Selection Mode

Use CalendarSelectionMode.Single with the selectionMode parameter for explicit single-date selection. This is the recommended approach when you need the full selectionMode parameter — for instance when combining it with other CalendarSelectionMode variants in your codebase.

Date Restriction Modes

Use dateSelectionMode to restrict which dates are clickable. Disabled dates are rendered with a muted color and cannot be tapped.

Past or Today

Future or Today

DateSelectionMode values and their behavior:

Mode	Clickable dates
`All` (default)	Every date in the grid
`PastOrToday`	Today and any date before today
`FutureOrToday`	Today and any date after today

Range Calendar

Pass CalendarSelectionMode.Range to enable range selection. The first tap sets the start date, the second tap sets the end date and fires onRangeSelected. Tapping again after a complete range resets and starts a new selection. If the second tap is before the first, the dates are automatically swapped.

Initial Month

By default the calendar opens on the current month. Use initialMonth to open on a specific YearMonth.

initialMonth is only used on first composition. To programmatically navigate months after the calendar is rendered, hoist the state into a YearMonth variable and pass it each time.

Parameter	Type	Default	Description
`modifier`	`Modifier`	`Modifier`	Applied to the calendar container.
`selectedDate`	`LocalDate?`	`null`	The currently selected date.
`onDateSelected`	`(LocalDate) -> Unit`	—	Called when the user taps a date.
`initialMonth`	`YearMonth`	`YearMonth.now()`	The month shown on first render.
`dateSelectionMode`	`DateSelectionMode`	`DateSelectionMode.All`	Controls which dates are clickable.
`colors`	`CalendarStyle`	`CalendarDefaults.colors()`	Color tokens for the calendar.

Calendar (selectionMode overload)

Full overload used for both single and range selection.

Parameter	Type	Default	Description
`modifier`	`Modifier`	`Modifier`	Applied to the calendar container.
`selectionMode`	`CalendarSelectionMode`	—	Single or range selection configuration.
`initialMonth`	`YearMonth`	`YearMonth.now()`	The month shown on first render.
`dateSelectionMode`	`DateSelectionMode`	`DateSelectionMode.All`	Controls which dates are clickable.
`colors`	`CalendarStyle`	`CalendarDefaults.colors()`	Color tokens for the calendar.

DateSelectionMode

Enum that restricts which dates are tappable.

Value	Description
`All`	All dates are enabled.
`PastOrToday`	Only today and past dates are enabled.
`FutureOrToday`	Only today and future dates are enabled.

CalendarSelectionMode

Sealed interface defining the selection behavior.

`CalendarSelectionMode.Single`

Parameter	Type	Default	Description
`selectedDate`	`LocalDate?`	`null`	The currently selected date.
`onDateSelected`	`(LocalDate) -> Unit`	—	Called when the user taps a date.

`CalendarSelectionMode.Range`

Parameter	Type	Default	Description
`selectedRange`	`DateRange?`	`null`	The currently selected date range.
`onRangeSelected`	`(DateRange) -> Unit`	—	Called when the user completes a range selection.

DateRange

data class DateRange(val start: LocalDate, val end: LocalDate)

Holds the start and end dates of a range selection.

YearMonth

Helper class used for calendar navigation. Provides factory methods and arithmetic operators.

Member	Description
`YearMonth.now()`	Returns the current year-month from the system clock.
`YearMonth.from(date: LocalDate)`	Creates a `YearMonth` from a `LocalDate`.
`plusMonths(n)`	Returns a new `YearMonth` advanced by `n` months.
`minusMonths(n)`	Returns a new `YearMonth` reduced by `n` months.
`atDay(day)`	Returns a `LocalDate` for the given day in this month.
`lengthOfMonth()`	Number of days in the month (leap-year aware).

CalendarStyle

All color tokens used to render the calendar. Obtain a default instance via CalendarDefaults.colors() and override fields using CalendarDefaults.colors { copy(...) }.

Field	Type	Description
`background`	`Color`	Background of the calendar container.
`border`	`Color`	Border around the calendar container.
`leftIconTint`	`Color`	Tint of the previous-month arrow icon.
`rightIconTint`	`Color`	Tint of the next-month arrow icon.
`monthText`	`Color`	Text color of the month selector chip.
`yearText`	`Color`	Text color of the year selector chip.
`monthSelectorBorder`	`Color`	Border of the month selector chip.
`yearSelectorBorder`	`Color`	Border of the year selector chip.
`weekDaysText`	`Color`	Text color of the weekday header row (Sun–Sat).
`dateCellBgStyle`	`DateCellBackgroundStyle`	Background colors for individual day cells.
`dateCellTextStyle`	`DateCellTextStyle`	Text colors for individual day cells.
`dialogStyle`	`SelectorDialogStyle`	Colors for the month/year picker dialogs.

DateCellBackgroundStyle

Field	Type	Description
`selectedDate`	`Color`	Background of the selected date cell.
`todayUnselectedBg`	`Color`	Background of today's cell when not selected.
`onPressed`	`Color`	Background color during press animation.
`defaultDateCell`	`Color`	Background of a normal, unselected date cell.
`rangeEndpointBg`	`Color`	Background of the range start/end cells.
`inRangeBg`	`Color`	Background of cells between the range endpoints.

DateCellTextStyle

Field	Type	Description
`selectedDate`	`Color`	Text color of the selected date.
`todayUnselected`	`Color`	Text color of today when not selected.
`currentMonthUnselected`	`Color`	Text color of normal, unselected days in the current month.
`currentMonthDisabled`	`Color`	Text color of disabled days in the current month.
`previousAndNextDateMonth`	`Color`	Text color of days spilling from the previous/next month.
`previousAndNextDateMonthDisabled`	`Color`	Text color of disabled days outside the current month.
`rangeEndpointText`	`Color`	Text color of the range start/end cells.
`inRangeText`	`Color`	Text color of cells between the range endpoints.

SelectorDialogStyle

Shared color scheme for the month and year picker dialogs.

Field	Type	Description
`selectedBg`	`Color`	Background of the currently selected item.
`selectedText`	`Color`	Text color of the currently selected item.
`unselectedBg`	`Color`	Background of unselected items.
`unselectedText`	`Color`	Text color of unselected items.

CalendarDefaults

Member	Description
`colors()`	Returns a `CalendarStyle` populated from the current Material theme.
`colors { copy(...) }`	Returns a `CalendarStyle` with selective overrides applied via a lambda.

Edit this page on GitHub