Component reference
Calendar
Select dates for a booking in a standalone calendar.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Sundays are closed and past dates are unavailable.
Width adapts to the available space
"use client";
import { useState } from "react";
import { Calendar, Badge } from "@pimolu/react";
const DEMO_MONTH = new Date(2026, 9, 1);
const TODAY = new Date(2026, 9, 20);
function formatDate(date: Date | null, locale = "en-US", options: Intl.DateTimeFormatOptions = {
year: "numeric",
month: "long",
day: "numeric",
}) {
if(!date)
return "—";
return new Intl.DateTimeFormat(locale, options).format(date);
}
function closedOnSundays(date: Date) {
return date.getDay() === 0;
}
function BookingExample() {
const [date, setDate] = useState<Date | null>(null);
return (
<div className="grid gap-5 min-w-0">
<Calendar
aria-label="Consultation date"
defaultMonth={DEMO_MONTH}
selected={date}
onSelect={setDate}
min={TODAY}
max={new Date(2026, 11, 31)}
disabledDates={closedOnSundays}
/>
<div className="flex flex-wrap items-center gap-3 min-w-0 justify-between">
<span className="text-sm text-muted leading-relaxed">Consultation</span>
<Badge variant={date ? "success" : "neutral"} appearance="soft">
{
date
? formatDate(
date,
"en-US",
{
weekday: "short",
month: "short",
day: "numeric",
}
)
: "Not scheduled"
}
</Badge>
</div>
<p className="text-sm text-muted leading-relaxed">
Sundays are closed and past dates are unavailable.
</p>
</div>
);
}
export function DemoExample() {
return (<BookingExample />);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Single date
Arrow keys move by day, PageUp/PageDown by month, Home/End across the week. Enter or Space selects the focused day.
Range
The first click sets the start, the second sets the end, and the next click starts a new range. A range can be completed in either direction.
Two months
numberOfMonths renders consecutive grids and keeps them in sync while navigating.
Usage
Keep local calendar-day semantics and apply availability limits explicitly.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluDateRange
Type source| Name | Type | Default | Description |
|---|---|---|---|
fromRequired | Date | null | — | Public Pimolu prop; see the source declaration for details. |
toRequired | Date | null | — | Public Pimolu prop; see the source declaration for details. |
fromRequiredDate | nullNo default extracted.
Public Pimolu prop; see the source declaration for details.
toRequiredDate | nullNo default extracted.
Public Pimolu prop; see the source declaration for details.
PimoluCalendarProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
mode | PimoluCalendarMode | undefined | "single" | Selection model. Defaults to "single". |
selected | Date | null | undefined | — | Controlled single selection. Omit to let the calendar own it; pass `null` to control an empty selection. |
onSelect | ((date: Date) => void) | undefined | — | Called with the selected day when `mode` is "single". |
range | PimoluDateRange | undefined | — | Controlled range selection. Omit to let the calendar own it. When the first click sets `from`, the second sets `to`, and a third starts a new range. |
onRangeChange | ((range: PimoluDateRange) => void) | undefined | — | Called whenever the range changes. |
month | Date | undefined | — | Controlled visible month. Any day in the month is accepted. |
defaultMonth | Date | undefined | — | Initial visible month when uncontrolled. |
onMonthChange | ((month: Date) => void) | undefined | — | Called with the first day of the month after prev/next navigation. |
min | Date | undefined | — | Earliest selectable day, inclusive. |
max | Date | undefined | — | Latest selectable day, inclusive. |
disabledDates | PimoluDisabledDates | undefined | — | Dates that cannot be selected, as a list or a predicate. |
weekStartsOn | 0 | 1 | undefined | 0 | First day of the week: 0 = Sunday, 1 = Monday. Defaults to 0. |
locale | string | undefined | "en-US" | BCP 47 locale used for month, weekday and day labels. Defaults to "en-US". |
numberOfMonths | 1 | 2 | undefined | 1 | Number of consecutive months rendered together. Defaults to 1. |
className | string | undefined | — | Class applied to the outer calendar. |
aria-label | string | undefined | — | Accessible name for the calendar group. |
modePimoluCalendarMode | undefinedDefault: "single"
Selection model. Defaults to "single".
selectedDate | null | undefinedNo default extracted.
Controlled single selection. Omit to let the calendar own it; pass `null` to control an empty selection.
onSelect((date: Date) => void) | undefinedNo default extracted.
Called with the selected day when `mode` is "single".
rangePimoluDateRange | undefinedNo default extracted.
Controlled range selection. Omit to let the calendar own it. When the first click sets `from`, the second sets `to`, and a third starts a new range.
onRangeChange((range: PimoluDateRange) => void) | undefinedNo default extracted.
Called whenever the range changes.
monthDate | undefinedNo default extracted.
Controlled visible month. Any day in the month is accepted.
defaultMonthDate | undefinedNo default extracted.
Initial visible month when uncontrolled.
onMonthChange((month: Date) => void) | undefinedNo default extracted.
Called with the first day of the month after prev/next navigation.
minDate | undefinedNo default extracted.
Earliest selectable day, inclusive.
maxDate | undefinedNo default extracted.
Latest selectable day, inclusive.
disabledDatesPimoluDisabledDates | undefinedNo default extracted.
Dates that cannot be selected, as a list or a predicate.
weekStartsOn0 | 1 | undefinedDefault: 0
First day of the week: 0 = Sunday, 1 = Monday. Defaults to 0.
localestring | undefinedDefault: "en-US"
BCP 47 locale used for month, weekday and day labels. Defaults to "en-US".
numberOfMonths1 | 2 | undefinedDefault: 1
Number of consecutive months rendered together. Defaults to 1.
classNamestring | undefinedNo default extracted.
Class applied to the outer calendar.
aria-labelstring | undefinedNo default extracted.
Accessible name for the calendar group.
Accessibility
- Verify arrow navigation, disabled dates, locale labels and the selected-date announcement.