Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/raystack/apsara/llms.txt

Use this file to discover all available pages before exploring further.

The Calendar component provides flexible date selection interfaces. It includes Calendar for inline display, DatePicker for single date selection, and RangePicker for selecting date ranges.

​
Components

The calendar module exports three main components:
  • Calendar: Base calendar component for inline date display and selection
  • DatePicker: Input field with popover calendar for single date selection
  • RangePicker: Input fields with popover calendar for date range selection

​
Calendar

The base Calendar component displays a calendar interface for date selection.

​
Basic usage

import { Calendar } from '@raystack/apsara';

function App() {
  return <Calendar mode="single" selected={new Date()} />;
}

​
Props

​
mode
'single' | 'multiple' | 'range'
default:"'single'"
The selection mode of the calendar.
​
selected
Date | Date[] | DateRange
The selected date(s). Type depends on mode.
​
onSelect
(date: Date | Date[] | DateRange) => void
Callback fired when a date is selected.
​
month
Date
The month to display.
​
onMonthChange
(month: Date) => void
Callback fired when the month changes.
​
startMonth
Date
The earliest month that can be displayed.
​
endMonth
Date
The latest month that can be displayed.
​
disabled
boolean | Date | Date[] | ((date: Date) => boolean)
Dates to disable. Can be a boolean, specific dates, or a function.
​
showOutsideDays
boolean
default:"true"
Whether to show days outside the current month.
​
showTooltip
boolean
default:"false"
Whether to show tooltips on date hover.
​
tooltipMessages
Record<string, ReactNode>
default:"{}"
Tooltip messages for specific dates. Keys should be in ‘dd-MM-yyyy’ format.
​
dateInfo
Record<string, ReactNode> | ((date: Date) => ReactNode | null)
default:"{}"
Additional info to display on dates. Can be an object or function.
​
loadingData
boolean
default:"false"
Whether the calendar is in a loading state.
​
timeZone
string
The timezone to use for date calculations.
​
numberOfMonths
number
Number of months to display.
​
className
string
Additional CSS classes to apply to the calendar.

​
Single date selection

function SingleDateCalendar() {
  const [date, setDate] = useState(new Date());

  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
    />
  );
}

​
With tooltips and date info

<Calendar
  mode="single"
  showTooltip
  tooltipMessages={{
    '25-12-2024': 'Christmas Day',
    '01-01-2025': 'New Year'
  }}
  dateInfo={{
    '25-12-2024': '🎄',
    '01-01-2025': '🎉'
  }}
/>

​
DatePicker

A date picker with an input field that opens a calendar popover.

​
Basic usage

import { DatePicker } from '@raystack/apsara';

function App() {
  return <DatePicker onSelect={(date) => console.log(date)} />;
}

​
Props

​
value
Date
default:"new Date()"
The selected date value.
​
onSelect
(date: Date) => void
Callback fired when a date is selected.
​
dateFormat
string
default:"'DD/MM/YYYY'"
The format for displaying the date in the input field.
​
inputFieldProps
InputFieldProps
Props to pass to the underlying InputField component.
​
calendarProps
CalendarProps
Props to pass to the underlying Calendar component.
​
showCalendarIcon
boolean
default:"true"
Whether to show the calendar icon in the input field.
​
timeZone
string
The timezone to use for date calculations.
​
popoverProps
PopoverContentProps
Props to pass to the Popover.Content component.
​
children
ReactNode | ((props: { selectedDate: string }) => ReactNode)
Custom trigger element or render function.

​
Controlled date picker

function ControlledDatePicker() {
  const [date, setDate] = useState(new Date());

  return (
    <DatePicker
      value={date}
      onSelect={setDate}
      inputFieldProps={{
        label: 'Select date',
        helperText: 'Choose a date from the calendar'
      }}
    />
  );
}

​
Custom date format

<DatePicker
  dateFormat="MM-DD-YYYY"
  inputFieldProps={{ label: 'Date' }}
/>

​
With date restrictions

<DatePicker
  calendarProps={{
    startMonth: new Date(2024, 0, 1),
    endMonth: new Date(2024, 11, 31),
    disabled: (date) => date.getDay() === 0 || date.getDay() === 6
  }}
/>

​
Custom trigger

<DatePicker>
  {({ selectedDate }) => (
    <button>{selectedDate || 'Pick a date'}</button>
  )}
</DatePicker>

​
RangePicker

A date range picker with two input fields for start and end dates.

​
Basic usage

import { RangePicker } from '@raystack/apsara';

function App() {
  return <RangePicker onSelect={(range) => console.log(range)} />;
}

​
Props

​
value
DateRange
The selected date range value with from and to properties.
​
defaultValue
DateRange
default:"{ from: new Date(), to: new Date() }"
The default date range for uncontrolled usage.
​
onSelect
(range: DateRange) => void
Callback fired when a date range is selected.
​
dateFormat
string
default:"'DD/MM/YYYY'"
The format for displaying dates in the input fields.
​
inputFieldsProps
{ startDate?: InputFieldProps; endDate?: InputFieldProps }
Props for the start and end date input fields.
​
calendarProps
CalendarProps
Props to pass to the underlying Calendar component.
​
showCalendarIcon
boolean
default:"true"
Whether to show calendar icons in the input fields.
​
pickerGroupClassName
string
CSS class for the container wrapping both input fields.
​
footer
ReactNode
Footer content to display below the calendar.
​
timeZone
string
The timezone to use for date calculations.
​
popoverProps
PopoverContentProps
Props to pass to the Popover.Content component.
​
children
ReactNode | ((props: { startDate: string; endDate: string }) => ReactNode)
Custom trigger element or render function.

​
Controlled range picker

function ControlledRangePicker() {
  const [range, setRange] = useState({
    from: new Date(),
    to: new Date()
  });

  return (
    <RangePicker
      value={range}
      onSelect={setRange}
      inputFieldsProps={{
        startDate: { label: 'Start date' },
        endDate: { label: 'End date' }
      }}
    />
  );
}

​
With footer

<RangePicker
  footer={
    <Button size="small" onClick={() => handleApply()}>
      Apply Range
    </Button>
  }
/>

​
Custom date format

<RangePicker dateFormat="YYYY-MM-DD" />

​
Preset ranges example

function RangePickerWithPresets() {
  const [range, setRange] = useState({ from: new Date(), to: new Date() });
  
  const presets = {
    'Last 7 days': {
      from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
      to: new Date()
    },
    'Last 30 days': {
      from: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
      to: new Date()
    }
  };

  return (
    <div>
      <div>
        {Object.entries(presets).map(([label, preset]) => (
          <Button
            key={label}
            size="small"
            variant="outline"
            onClick={() => setRange(preset)}
          >
            {label}
          </Button>
        ))}
      </div>
      <RangePicker value={range} onSelect={setRange} />
    </div>
  );
}

​
Accessibility

  • All calendar components support full keyboard navigation.
  • Arrow keys navigate between dates, Enter/Space to select.
  • Month and year dropdowns are keyboard accessible.
  • Proper ARIA labels are applied to navigation buttons.
  • Screen readers announce selected dates and date ranges.
  • The DatePicker input field supports manual date entry with validation.
  • Focus management ensures smooth interaction between input and calendar.

Build docs developers (and LLMs) love

Get started for freeTalk to us