Calendar

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

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

'single' | 'multiple' | 'range'

default:"'single'"

The selection mode of the calendar.

Date | Date[] | DateRange

The selected date(s). Type depends on mode.

(date: Date | Date[] | DateRange) => void

Callback fired when a date is selected.

Date

The month to display.

(month: Date) => void

Callback fired when the month changes.

Date

The earliest month that can be displayed.

Date

The latest month that can be displayed.

boolean | Date | Date[] | ((date: Date) => boolean)

Dates to disable. Can be a boolean, specific dates, or a function.

boolean

default:"true"

Whether to show days outside the current month.

Whether to show tooltips on date hover.

Tooltip messages for specific dates. Keys should be in ‘dd-MM-yyyy’ format.

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

default:"{}"

Additional info to display on dates. Can be an object or function.

boolean

default:"false"

Whether the calendar is in a loading state.

string

The timezone to use for date calculations.

number

Number of months to display.

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

Date

default:"new Date()"

The selected date value.

(date: Date) => void

Callback fired when a date is selected.

string

default:"'DD/MM/YYYY'"

The format for displaying the date in the input field.

InputFieldProps

Props to pass to the underlying InputField component.

CalendarProps

Props to pass to the underlying Calendar component.

boolean

default:"true"

Whether to show the calendar icon in the input field.

string

The timezone to use for date calculations.

Props to pass to the Popover.Content component.

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

DateRange

The selected date range value with from and to properties.

DateRange

default:"{ from: new Date(), to: new Date() }"

The default date range for uncontrolled usage.

(range: DateRange) => void

Callback fired when a date range is selected.

string

default:"'DD/MM/YYYY'"

The format for displaying dates in the input fields.

{ startDate?: InputFieldProps; endDate?: InputFieldProps }

Props for the start and end date input fields.

CalendarProps

Props to pass to the underlying Calendar component.

boolean

default:"true"

Whether to show calendar icons in the input fields.

string

CSS class for the container wrapping both input fields.

ReactNode

Footer content to display below the calendar.

string

The timezone to use for date calculations.

Props to pass to the Popover.Content component.

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.

Get Started

Guides

Layout Components

Navigation Components

Data Display

Form Components

Feedback Components

Overlay Components

Utility Components

Calendar

Components

Calendar

Basic usage

Props

Single date selection

With tooltips and date info

DatePicker

Basic usage

Props

Controlled date picker

Custom date format

With date restrictions

Custom trigger

RangePicker

Basic usage

Props

Controlled range picker

With footer

Custom date format

Preset ranges example

Accessibility

​Components

​Calendar

​Basic usage

​Props

​Single date selection

​With tooltips and date info

​DatePicker

​Basic usage

​Props

​Controlled date picker

​Custom date format

​With date restrictions

​Custom trigger

​RangePicker

​Basic usage

​Props

​Controlled range picker

​With footer

​Custom date format

​Preset ranges example

​Accessibility

Components

Calendar

Basic usage

Props

Single date selection

With tooltips and date info

DatePicker

Basic usage

Props

Controlled date picker

Custom date format

With date restrictions

Custom trigger

RangePicker

Basic usage

Props

Controlled range picker

With footer

Custom date format

Preset ranges example

Accessibility