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()} />;
}
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.
Callback fired when the month changes.
The earliest month that can be displayed.
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.
Whether to show days outside the current month.
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.
Whether the calendar is in a loading state.
The timezone to use for date calculations.
Number of months to display.
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)} />;
}
Callback fired when a date is selected.
dateFormat
string
default:"'DD/MM/YYYY'"
The format for displaying the date in the input field.
Props to pass to the underlying InputField component.
Props to pass to the underlying Calendar component.
Whether to show the calendar icon in the input field.
The timezone to use for date calculations.
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)} />;
}
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.
Props to pass to the underlying Calendar component.
Whether to show calendar icons in the input fields.
CSS class for the container wrapping both input fields.
Footer content to display below the calendar.
The timezone to use for date calculations.
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' }
}}
/>
);
}
<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.