Prepared Docs

Overview

@prepared911/ui-calendar exports three building blocks that DatePicker composes internally and that you can reuse when a custom calendar layout is genuinely needed:

SelectMonth: a Select over the locale's month names, with optional minDate / maxDate clamping.
SelectYear: a Select over a year range (default: 2020–currentYear).
MonthCaption: the chevron + month / year Select header used by DatePicker.

They sit in the components/ subpath of the package and are surfaced at the top level via the shared index. Reach for them only when you are building a react-day-picker surface that DatePicker can't express—e.g. a multi-month grid or a non-standard caption layout. In most cases, the answer is to use DatePicker directly.

When to use

Custom calendar surfaces. A multi-month grid, a product-specific year range, or a caption with extra controls that DatePicker does not offer.
Standalone month / year pickers. Reports and analytics surfaces that operate at the month or year granularity rather than day-level.

When not to use

Replacing MonthCaption inside a standard DatePicker. If the existing caption layout meets the need, use it: maintenance cost rises every time DatePicker changes upstream.
Generic <select> dropdowns. These components are tuned for month / year selection with calendar constraints. For generic dropdowns, use @prepared911/ui-core Select directly.

Customization

SelectMonth. Pass selectedYear along with minDate / maxDate so months outside the range are disabled. Without maxDate, future months in the current year are auto-disabled.
SelectYear. Override minYear / maxYear for surfaces with different historical ranges (e.g. a five-year analytics window).
MonthCaption. Supports hideMonthYearSelect to fall back to chevron-only navigation and minSelectableDate / maxSelectableDate for fully constrained layouts.

Best practices

Keep minSelectableDate / maxSelectableDate aligned across MonthCaption, SelectMonth, and SelectYear so the grid, the month Select, and the year Select never present empty option sets.
Default to DatePicker for day-level selection and reach for these primitives only when the surface genuinely needs a custom layout.
Localize month names via getMonthNamesFull() (which these components already use): don't hardcode a month array.

Don't

Don't duplicate MonthCaption inside a standard DatePicker: use DatePicker's caption directly unless design requires a divergent layout.
Don't hand-roll a month or year Select with raw strings; SelectMonth / SelectYear already localize and clamp correctly.

Accessibility

All three primitives render @prepared911/ui-core Selects or IconButtons that expose the current value to assistive technology. When you compose them into a custom DayPicker, follow react-day-picker's caption guidance so screen readers announce month and year changes predictably. See the Accessibility page for the full contract.

Date Picker: the default consumer of these primitives.
Date Input: the popover-anchored field variant.

Advanced Date Time Range Picker / Accessibility

Calendar Utilities / API and Development

Overview

@prepared911/ui-calendar exports three building blocks that DatePicker composes internally and that you can reuse when a custom calendar layout is genuinely needed:

SelectMonth: a Select over the locale's month names, with optional minDate / maxDate clamping.
SelectYear: a Select over a year range (default: 2020–currentYear).
MonthCaption: the chevron + month / year Select header used by DatePicker.

When to use

Custom calendar surfaces. A multi-month grid, a product-specific year range, or a caption with extra controls that DatePicker does not offer.
Standalone month / year pickers. Reports and analytics surfaces that operate at the month or year granularity rather than day-level.

When not to use

Replacing MonthCaption inside a standard DatePicker. If the existing caption layout meets the need, use it: maintenance cost rises every time DatePicker changes upstream.
Generic <select> dropdowns. These components are tuned for month / year selection with calendar constraints. For generic dropdowns, use @prepared911/ui-core Select directly.

Customization

SelectMonth. Pass selectedYear along with minDate / maxDate so months outside the range are disabled. Without maxDate, future months in the current year are auto-disabled.
SelectYear. Override minYear / maxYear for surfaces with different historical ranges (e.g. a five-year analytics window).
MonthCaption. Supports hideMonthYearSelect to fall back to chevron-only navigation and minSelectableDate / maxSelectableDate for fully constrained layouts.

Best practices

Keep minSelectableDate / maxSelectableDate aligned across MonthCaption, SelectMonth, and SelectYear so the grid, the month Select, and the year Select never present empty option sets.
Default to DatePicker for day-level selection and reach for these primitives only when the surface genuinely needs a custom layout.
Localize month names via getMonthNamesFull() (which these components already use): don't hardcode a month array.

Don't

Don't duplicate MonthCaption inside a standard DatePicker: use DatePicker's caption directly unless design requires a divergent layout.
Don't hand-roll a month or year Select with raw strings; SelectMonth / SelectYear already localize and clamp correctly.