# Calendar

- Page: https://jiguang132.com/resources/astryx/docs/calendar
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```json
{
  "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.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt