Forms

Calendar

Renders accessible single and range date selection with month navigation, disabled bounds, and locale-aware formatting.

idle

Usage

import { Calendar } from "@mizen-labs/ui";

Examples

Single date

Date range

Month and year navigation

Jump directly to a month or year using Mizen Select. Navigation bounds define the available years.

Recommendations

Guidance	Practice
Do	Specify locale and unavailable dates. Use range mode when the task selects a stay or reporting interval.
Do	Use minValue, maxValue, or isDateUnavailable for real date constraints.

Usage boundaries

Guidance	Boundary
Scope	Use Date Picker for compact editable entry. Date availability and booking rules belong to the application.

API reference

Public props from @mizen-labs/ui. Use exported prop types for the complete TypeScript contract.

Prop	Type	Default	Description
`mode`	`"single" \| "range"`	`—`	Selection mode for the calendar: single date selection or range selection.
`value`	`Date \| CalendarRangeValue \| undefined`	`—`	Controlled selection value: Date for single mode or CalendarRangeValue for range mode.
`defaultValue`	`Date \| CalendarRangeValue \| undefined`	`—`	Initial selection value in uncontrolled mode: Date for single mode or CalendarRangeValue for range mode.
`onValueChange`	`((value: Date \| undefined) => void) \| ((value: CalendarRangeValue \| undefined) => void)`	`—`	Event handler called when date selection changes with the selected Date or CalendarRangeValue.
`month`	`Date`	`—`	Controlled month currently displayed in the calendar.
`defaultMonth`	`Date`	`Current month or month of initial value`	Initial month displayed when uncontrolled.
`onMonthChange`	`(month: Date) => void`	`—`	Event handler called when the displayed month changes.
`locale`	`CalendarLocale`	`—`	Locale object used for formatting months, weekdays, and accessible labels.
`dir`	`"ltr" \| "rtl"`	`"ltr"`	Text and layout direction for the calendar grid and navigation.
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	`0 (Sunday)`	First day of the week, where 0 is Sunday and 1 is Monday.
`autoFocus`	`boolean`	`false`	Automatically focuses the selected or initial day button on mount.
`required`	`boolean`	`false`	Prevents deselecting the current value when clicked.
`disabled`	`boolean`	`false`	Disables all date selection and month navigation controls.
`readOnly`	`boolean`	`false`	Prevents selection changes while preserving focus and keyboard navigation.
`invalid`	`boolean`	`false`	Renders invalid accessibility semantics and styling on the calendar root.
`minValue`	`Date`	`—`	Earliest selectable date. Dates before this are disabled.
`maxValue`	`Date`	`—`	Latest selectable date. Dates after this are disabled.
`isDateUnavailable`	`(date: Date) => boolean`	`—`	Predicate function returning true for specific disabled dates.
`minNights`	`number`	`—`	Minimum number of nights required for a completed range in range mode.
`maxNights`	`number`	`—`	Maximum number of nights permitted for a completed range in range mode.
`Calendar`	`CalendarProps`	`"div"`	Root calendar component container with owned layout and navigation slots.
`CalendarRangeValue`	`{ from: Date; to?: Date }`	`—`	Range selection object with a required start date and optional end date.
`captionLayout`	`"label" \| "dropdown"`	`"label"`	Use dropdown to navigate directly with month and year selects.
`startMonth`	`Date`	`100 years before today in dropdown mode`	First month available for navigation. Does not change date availability.
`endMonth`	`Date`	`End of the current year in dropdown mode`	Last month available for navigation. Does not change date availability.