Calendar

1<Calendar />

Anatomy

Import and assemble the component:

1import { Calendar, RangePicker, DatePicker } from '@raystack/apsara'
2
3<Calendar />
4
5<RangePicker />
6
7<DatePicker />

API Reference

Calendar

Renders a standalone calendar for date selection.

numberOfMonths

number

captionLayout

"label" | "dropdown" | "dropdown-months" | "dropdown-years"

startMonth

Date

endMonth

Date

defaultMonth

Date

month

Date

onMonthChange

((month: Date) => void)

mode

"single" | "multiple" | "range"

selected

Date | Date[] | { from: Date; to?: Date | undefined; }

onSelect

((selected: Date | Date[] | { from: Date; to?: Date | undefined; }) => void)

weekStartsOn

0 | 1 | 2 | 3 | 4 | 5 | 6

showWeekNumber

boolean

disabled

Date | Date[] | { before?: Date | undefined; after?: Date | undefined; from?: Date | undefined; to?: Date | undefined; } | ((date: Date) => boolean)

hidden

Date | Date[] | { before?: Date | undefined; after?: Date | undefined; from?: Date | undefined; to?: Date | undefined; } | ((date: Date) => boolean)

loadingData

boolean

showTooltip

boolean

tooltipMessages

Record<string, ReactNode>

dateInfo

Record<string, ReactNode> | ((date: Date) => ReactNode)

onDropdownOpen

(() => void)

showOutsideDays

boolean

footer

ReactNode

classNames

Record<string, string>

className

string

timeZone

string

RangePicker

The RangePicker exposes its slots — startInput, endInput, calendar, popover — through the slotProps prop.

dateFormat

string

onSelect

((range: { from?: Date | undefined; to?: Date | undefined; }) => void)

defaultValue

{ from?: Date | undefined; to?: Date | undefined; }

value

{ from?: Date | undefined; to?: Date | undefined; }

slotProps

{ startInput?: InputProps | undefined; endInput?: InputProps | undefined; calendar?: CalendarProps | undefined; popover?: PopoverContentProps | undefined; }

calendarProps

CalendarProps

inputsProps

{ startDate?: InputProps | undefined; endDate?: InputProps | undefined; }

children

ReactNode | ((props: { startDate: string; endDate: string; }) => ReactNode)

showCalendarIcon

boolean

footer

ReactNode

timeZone

string

popoverProps

PopoverContentProps

DatePicker

The DatePicker exposes its slots — input, calendar, popover — through the slotProps prop.

dateFormat

string

slotProps

{ input?: InputProps | undefined; calendar?: CalendarProps | undefined; popover?: PopoverContentProps | undefined; }

inputProps

InputProps

value

Date

defaultValue

Date

onSelect

((date: Date) => void)

calendarProps

CalendarProps

children

ReactNode | ((props: { selectedDate: string; }) => ReactNode)

showCalendarIcon

boolean

timeZone

string

popoverProps

PopoverContentProps

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

Slot	Element
`calendar`	The root calendar surface
`calendar-nav-previous`	The previous-month navigation button
`calendar-nav-next`	The next-month navigation button
`calendar-dropdown`	The month/year dropdown trigger (when `captionLayout="dropdown"`)
`calendar-dropdown-content`	The dropdown's option list (when the dropdown is open)
`calendar-month-grid`	Wrapper around the day grid and its skeleton
`calendar-grid-table`	The `<table>` that holds the days
`calendar-grid-skeleton`	The loading skeleton shown over the grid
`calendar-day`	The `<button>` for a single day
`calendar-day-info`	Extra info shown inside a day (when `dateInfo` resolves for that day)
`calendar-day-number`	The day number inside a day button
`calendar-day-tooltip`	The tooltip shown on hover (when `showTooltip` and a message exists)
`date-picker-trigger`	The `<div>` wrapping the DatePicker trigger
`date-picker-input`	The DatePicker's text `<input>`
`date-picker-error`	The error message (always mounted, toggled via `data-visible`)
`date-picker-positioner`	The popover positioner for the DatePicker
`date-picker-content`	The DatePicker popover content that holds the calendar
`range-picker-trigger`	The `<div>` wrapping the RangePicker trigger
`range-picker-trigger-group`	The row that groups the start and end inputs
`range-picker-start-input`	The RangePicker's start date `<input>`
`range-picker-end-input`	The RangePicker's end date `<input>`
`range-picker-positioner`	The popover positioner for the RangePicker
`range-picker-content`	The RangePicker popover content that holds the calendar
`range-picker-footer`	The footer below the calendar (when `footer` is set)

Examples

Calendar

Layout & appearance

Number of months, dropdown nav, loading state, footer.

1<Calendar
numberOfMonths={2}
defaultMonth={new Date(2025, 5, 1)}
showWeekNumber={false}
weekStartsOn={1}
showOutsideDays={false}
7/>

Behavior & data

Tooltips, disabled days, timezone, controlled month navigation.

1<Calendar
showTooltip
tooltipMessages={{
  "15-06-2026": "Holiday",
  "20-06-2026": "Team off-site",
}}
7/>

Custom date information

You can display custom components above each date using the dateInfo prop. The keys should be date strings in "dd-MM-yyyy" format, and the values are React components that will be rendered above the date number.

1<Calendar
numberOfMonths={2}
dateInfo={{
  [dayjs().format("DD-MM-YYYY")]: (
    <Flex
      align="center"
      gap={2}
      style={{
        fontSize: "8px",
        color: "var(--rs-color-foreground-base-secondary)",
      }}
    >
      <Info style={{ width: "8px", height: "8px" }} />
      <Text style={{ fontSize: "8px" }} color="secondary">
        25%

Range Picker

Selects a date range across two inputs. The grid uses a state machine that branches on the current from / to:

Empty — first click sets from and advances focus to the end input.
Only from set — clicking a later date completes the range and closes the popover; clicking an earlier date resets from.
Both set — clicking again restarts: the new date becomes from, to clears.

onSelect fires on every step (the shape is { from?: Date; to?: Date } — partial during interaction). Gate on range.to if you only want the completed-range event.

1<RangePicker />

Date Picker

Single-date selection with a typable input. The popover opens on focus; pressing Enter, blurring, or clicking outside commits the value and fires onSelect.

1<DatePicker slotProps={{ input: { size: "medium" } }} />

Accessibility

Supports keyboard navigation between dates with arrow keys
Uses aria-label attributes for date cells
Selected and disabled dates are announced to screen readers

Calendar

Anatomy

API Reference

Calendar

numberOfMonthsnumber

captionLayout"label" | "dropdown" | "dropdown-months" | "dropdown-years"

startMonthDate

endMonthDate

defaultMonthDate

monthDate

onMonthChange((month: Date) => void)

mode"single" | "multiple" | "range"

selectedDate | Date[] | { from: Date; to?: Date | undefined; }

onSelect((selected: Date | Date[] | { from: Date; to?: Date | undefined; }) => void)

weekStartsOn0 | 1 | 2 | 3 | 4 | 5 | 6

showWeekNumberboolean

disabledDate | Date[] | { before?: Date | undefined; after?: Date | undefined; from?: Date | undefined; to?: Date | undefined; } | ((date: Date) => boolean)

hiddenDate | Date[] | { before?: Date | undefined; after?: Date | undefined; from?: Date | undefined; to?: Date | undefined; } | ((date: Date) => boolean)

loadingDataboolean

showTooltipboolean

tooltipMessagesRecord<string, ReactNode>

dateInfoRecord<string, ReactNode> | ((date: Date) => ReactNode)

onDropdownOpen(() => void)

showOutsideDaysboolean

footerReactNode

classNamesRecord<string, string>

classNamestring

timeZonestring

RangePicker

dateFormatstring

onSelect((range: { from?: Date | undefined; to?: Date | undefined; }) => void)

defaultValue{ from?: Date | undefined; to?: Date | undefined; }

value{ from?: Date | undefined; to?: Date | undefined; }

slotProps{ startInput?: InputProps | undefined; endInput?: InputProps | undefined; calendar?: CalendarProps | undefined; popover?: PopoverContentProps | undefined; }

calendarPropsCalendarProps

inputsProps{ startDate?: InputProps | undefined; endDate?: InputProps | undefined; }

childrenReactNode | ((props: { startDate: string; endDate: string; }) => ReactNode)

showCalendarIconboolean

footerReactNode

timeZonestring

popoverPropsPopoverContentProps

DatePicker

dateFormatstring

slotProps{ input?: InputProps | undefined; calendar?: CalendarProps | undefined; popover?: PopoverContentProps | undefined; }

inputPropsInputProps

valueDate

defaultValueDate

onSelect((date: Date) => void)

calendarPropsCalendarProps

childrenReactNode | ((props: { selectedDate: string; }) => ReactNode)

showCalendarIconboolean

timeZonestring

popoverPropsPopoverContentProps

Slots

Examples

Calendar

Layout & appearance

Behavior & data

Custom date information

Range Picker

Date Picker

Accessibility