Calendar

Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Calendar

Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.

Prop	Type	Default	Description
mode	'single' \| 'range'	'single'	Selection mode.
value	ISODateString \| DateRange \| null		Controlled selected value. Use null for no selection; omit value or pass undefined for uncontrolled mode.
defaultValue	ISODateString \| DateRange		Uncontrolled default value.
onChange	Function		Selection callback.
numberOfMonths	1 \| 2	1	Number of months to display.
min	ISODateString		Minimum selectable date.
max	ISODateString		Maximum selectable date.
dateConstraints	Array<(date: Date) => boolean>		Custom constraint functions.
maxRangeSpan	number		Range mode: max days a range may span, both endpoints counted (7 = a 7-day window). Caps the window from the picked start; before a start is picked every day stays selectable.
minRangeSpan	number		Range mode: min days a range must span, both endpoints counted (2 forbids a single-day range). Clicking the start again commits a one-day range when allowed, or cancels the in-progress selection when the minimum is longer. Default 1.
focusDate	ISODateString		Controlled visible month. Unset, the calendar opens on the selected date, else on today clamped into the min/max window.
onFocusDateChange	(focusDate: ISODateString) => void		Navigation callback.
handleRef	React.Ref<CalendarHandle>		Imperative handle for calendar navigation, including navigateTo().
hasOutsideDays	boolean	true	Show days from adjacent months.
hasWeekNumbers	boolean	false	Show ISO week numbers.
hasVariableRowCount	boolean	false	Variable vs fixed 6-row grid.
weekStartsOn	0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'	0	First day of week. Accepts a number (0=Sunday) or a three-letter day name (e.g. "mon").

Usage guidance

Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.
Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.
Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.
Show two months side by side when the user frequently selects dates that span a month boundary.
Avoid: Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.
Avoid: Disable large blocks of dates without context. The user should understand why dates are unavailable.

Theming API

{
  "targets": [
    {
      "className": "astryx-calendar",
      "visualProps": [
        "mode"
      ]
    },
    {
      "className": "astryx-calendar-nav",
      "visualProps": [
        "nav"
      ],
      "states": [
        "disabled"
      ]
    },
    {
      "className": "astryx-calendar-day",
      "states": [
        "selected",
        "today",
        "disabled",
        "in-range",
        "marker"
      ]
    }
  ]
}

Anatomy

Calendar root: The container that holds the month header and the day grid.
Month header: The month name and year with navigation arrows to move between months. The arrows mirror automatically under dir="rtl".
Day grid: A 7-column grid of days with column headers for the day names.
Day button: One day in the grid; the control a date is picked with.
Selected day: The currently selected date, highlighted. In range mode, the start and end dates plus the days between them.
Today marker: A subtle indicator on the current date for orientation.

Examples

Calendar: An interactive single-date calendar with a selected date. Click any day to change the selection.
Calendar — Constraints: Limit which dates can be selected using min/max bounds and custom rules like weekdays only. Use for scheduling UIs where certain dates are unavailable.
Calendar — Range: Pick a start and end date with the range highlighted between them. Use for booking dates, time-off requests, or report filters.
Calendar — Single: Pick one date from a month grid. Use for appointment dates, due dates, or any field that needs a single date.
Calendar — Two Months: Two months side by side for selecting ranges that span a month boundary. Use in booking or travel UIs where check-in and check-out often fall in different months.