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 />

Usage

Calendar is the grid itself. DatePicker and RangePicker wrap it in a field and a popover, and all three share the props below.

Layout and 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/>

Behaviour and 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" } }} />

Controlled

Pass selected with onSelect to own the date. This is needed when the value comes from a form or has to be set from elsewhere, like a Today button.

1(function ControlledCalendar() {
const [date, setDate] = React.useState(new Date());
3
return (
  <Flex direction="column" align="center" gap={5}>
    <Calendar mode="single" selected={date} onSelect={setDate} />
    <Flex align="center" gap={4}>
      <Text size="small" variant="secondary">
        {date ? dayjs(date).format("D MMM YYYY") : "nothing selected"}
      </Text>
      <Button
        size="small"
        variant="outline"
        onClick={() => setDate(new Date())}
      >

API Reference

The bare grid, and the two pickers built on top of it.

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 startInput, endInput, calendar and popover slots 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; }

children

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

showCalendarIcon

boolean

footer

ReactNode

timeZone

string

DatePicker

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

dateFormat

string

slotProps

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

value

Date

defaultValue

Date

onSelect

((date: Date) => void)

onErrorChange

((error: string | undefined) => void)

calendarProps

CalendarProps

children

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

showCalendarIcon

boolean

timeZone

string

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-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)

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

Usage

Layout and appearance

Behaviour and data

Custom date information

Range picker

Date picker

Controlled

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; }

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

showCalendarIconboolean

footerReactNode

timeZonestring

DatePicker

dateFormatstring

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

valueDate

defaultValueDate

onSelect((date: Date) => void)

onErrorChange((error: string | undefined) => void)

calendarPropsCalendarProps

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

showCalendarIconboolean

timeZonestring

Slots

Accessibility