# Calendar (/forms/calendar)





<ComponentPreview name="calendar-preskok-demo" description="An interactive calendar for date selection." />

## Installation [#installation]

```bash
npx shadcn@latest add @preskok/calendar
```

## Usage [#usage]

```tsx
import { getLocalTimeZone, today } from "@internationalized/date"

import { Calendar } from "@/components/ui/preskok-ui/calendar"

export function CalendarDemo() {
  const [date, setDate] = useState(today(getLocalTimeZone()))

  return <Calendar value={date} onChange={setDate} aria-label="Select a date" />
}
```

## Props [#props]

| Prop                | Type                                | Default | Description                        |
| ------------------- | ----------------------------------- | ------- | ---------------------------------- |
| `value`             | `DateValue \| null`                 | -       | Selected date value                |
| `onChange`          | `(date: DateValue \| null) => void` | -       | Date change handler                |
| `minValue`          | `DateValue`                         | -       | Minimum selectable date            |
| `maxValue`          | `DateValue`                         | -       | Maximum selectable date            |
| `isDisabled`        | `boolean`                           | `false` | Disable the entire calendar        |
| `isReadOnly`        | `boolean`                           | `false` | Make calendar read-only            |
| `isDateUnavailable` | `(date: DateValue) => boolean`      | -       | Function to disable specific dates |
| `errorMessage`      | `string`                            | -       | Error message to display           |
| `className`         | `string`                            | -       | Additional CSS classes             |

## Examples [#examples]

### Basic [#basic]

<ComponentPreview name="calendar-preskok-demo" description="Select a single date in a basic calendar." />

### Controlled [#controlled]

<ComponentPreview name="calendar-controlled-preskok-demo" description="Control calendar state and display the selected date." />

### Controlled Month/Year [#controlled-monthyear]

<ComponentPreview name="calendar-controlled-month-year-preskok-demo" description="Control focused month/year externally and jump to today." />

### Disabled [#disabled]

<ComponentPreview name="calendar-disabled-preskok-demo" description="Show a disabled calendar with a preset date." />

### Unavailable Dates [#unavailable-dates]

<ComponentPreview name="calendar-with-disabled-dates-preskok-demo" description="Disable weekend dates via isDateUnavailable." />

### Min/Max Dates [#minmax-dates]

<ComponentPreview name="calendar-min-max-preskok-demo" description="Constrain selection to a three-month booking window." />

### Validation [#validation]

<ComponentPreview name="calendar-validation-preskok-demo" description="Validate weekday-only booking within a constrained range." />

### Date Range [#date-range]

<ComponentPreview name="calendar-with-range-preskok-demo" description="Select a start and end date in a range calendar." />

### Multiple Months [#multiple-months]

<ComponentPreview name="calendar-multiple-months-preskok-demo" description="Display two calendar months at once for range planning." />

## Features [#features]

* **Single date selection** - Select one date with clear focus and state handling
* **Month/year navigation** - Dropdown selectors for quick navigation
* **Date validation** - Min/max dates and custom unavailable dates
* **Internationalization** - Full i18n support with locale-aware formatting
* **Keyboard navigation** - Complete keyboard accessibility
* **Custom styling** - Extensive customization options
* **Time zones** - Proper time zone handling with @internationalized/date
* **Screen reader support** - Comprehensive accessibility features

## Accessibility [#accessibility]

The Calendar component follows WAI-ARIA guidelines:

* Proper grid structure with row/column headers
* Keyboard navigation with arrow keys
* Focus management and visual indicators
* Screen reader announcements for date changes
* Support for disabled and unavailable dates