# Calendar

> React calendar for Tailwind and shadcn: single, range or multiple dates, two months, preset ranges, a hover preview of the range and full arrow-key support.

- Kind: Component (Forms)
- Docs: https://ui.minidev.pro/docs/calendar
- Source (registry JSON with the full file): https://ui.minidev.pro/r/calendar.json
- License: MIT. One file, yours to edit after install.

## When to use

Use it inline or inside a Popover when people need to see the month: bookings, report periods, availability. Set `mode` to "single", "range" or "multiple"; `value` is then a `Date`, a `{ from, to }` range or a `Date[]`. `months={2}` shows two months side by side from the `sm` breakpoint, and `presets` adds a rail of ready-made ranges in range mode. Bound it with `min`, `max` and `disabled`. Month and day names come from `Intl.DateTimeFormat` in `locale`. It has no frame, so it sits flush in a Popover or card; on its own add `className="rounded-xl border border-border bg-surface shadow-raised"`. For a typed native field use DatePicker or DateRangePicker, for a date plus a time use DateTimePicker, and to show events use EventCalendar.

## Installation

### shadcn CLI (copies the source into your project)

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

Writes `components/ui/calendar.tsx` plus the MiniDev files it is built from (button) and installs its npm dependencies. Older CLI versions: `npx shadcn@latest add https://ui.minidev.pro/r/calendar.json`.

### npm package

```bash
npm i minidev-ui-kit lucide-react motion
```

Add the tokens to your global stylesheet once:

```css
@import "tailwindcss";
@import "minidev-ui-kit/styles.css";
@source "../node_modules/minidev-ui-kit";
```

Next.js also needs `transpilePackages: ["minidev-ui-kit"]` in next.config.

## Import

After the shadcn install:

```tsx
import { Calendar } from "@/components/ui/calendar"
```

From the npm package:

```tsx
import { Calendar } from "minidev-ui-kit/ui/calendar"
```

## Usage

```tsx
import { Calendar } from "@/components/ui/calendar"

export function Example() {
  return (
    <Calendar />
  )
}
```

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `mode` | `M` | `"single" as M` | no | "single" picks one day, "range" a from/to pair, "multiple" any set of days. |
| `value` | `CalendarValue<M> \| null` | - | no | Controlled selection: a Date, a `{ from, to }` range or a Date[], to match `mode`. |
| `defaultValue` | `CalendarValue<M> \| null` | `null` | no | Starting selection when uncontrolled. |
| `onValueChange` | `(value: CalendarValue<M>) => void` | - | no | Fires with the whole new selection on every pick. |
| `months` | `1 \| 2` | `1` | no | Months shown at once. Two sit side by side from the sm breakpoint and stack on phones. |
| `defaultMonth` | `Date` | - | no | The first month shown. Defaults to the selection's month, else the current month. |
| `min` | `Date` | - | no | Earliest day that can be picked. |
| `max` | `Date` | - | no | Latest day that can be picked. |
| `disabled` | `Date[] \| ((date: Date) => boolean)` | - | no | Days that cannot be picked: a list of dates or a test function. |
| `weekStartsOn` | `0 \| 1` | `0` | no | First column of the week: 0 is Sunday, 1 is Monday. |
| `locale` | `string` | `"en-US"` | no | BCP 47 locale for month, weekday and day labels. Fixed by default so server and client render the same text. |
| `presets` | `CalendarPreset[]` | - | no | Ready-made ranges shown in a rail beside the grid. Range mode only. |
| `showOutsideDays` | `boolean` | `true` | no | Show the days of the previous and next month in muted text. |
| `className` | `string` | - | no |  |

## Examples

### Delivery day

One day, bounded by min and max, with weekends disabled by a test function and Monday as the first column.

```tsx
function DeliveryDay() {
  const [day, setDay] = React.useState<Date>()
  return (
    <Calendar
      value={day}
      onValueChange={setDay}
      min={new Date(2026, 10, 16)}
      max={new Date(2026, 11, 18)}
      disabled={(d) => d.getDay() === 0 || d.getDay() === 6}
      weekStartsOn={1}
      className="rounded-xl border border-border bg-surface shadow-raised"
    />
  )
}
```

### Report period with presets

Two months side by side and a rail of preset ranges. After the first click, the band previews the range under the pointer.

```tsx
const today = new Date()
const daysAgo = (n: number) => new Date(today.getFullYear(), today.getMonth(), today.getDate() - n)
const presets: CalendarPreset[] = [
  { label: "Today", range: { from: today, to: today } },
  { label: "Last 7 days", range: { from: daysAgo(6), to: today } },
  { label: "Last 30 days", range: { from: daysAgo(29), to: today } },
  { label: "This month", range: { from: new Date(today.getFullYear(), today.getMonth(), 1), to: today } },
]

function ReportPeriod() {
  const [range, setRange] = React.useState<DateRange>({ from: daysAgo(6), to: today })
  return <Calendar mode="range" months={2} value={range} onValueChange={setRange} presets={presets} max={today} className="rounded-xl border border-border bg-surface shadow-raised" />
}
```

### On-call rota

Multiple mode toggles each day on and off and returns the days sorted.

```tsx
function OnCallDays() {
  const [days, setDays] = React.useState<Date[]>([new Date(2026, 10, 20), new Date(2026, 10, 21)])
  return <Calendar mode="multiple" value={days} onValueChange={setDays} weekStartsOn={1} className="rounded-xl border border-border bg-surface shadow-raised" />
}
```

## Keyboard interactions

| Key | Action |
| --- | --- |
| `ArrowLeft` or `ArrowRight` | Moves focus one day back or forward. Past the edge of the visible months, the next or previous month slides in. |
| `ArrowUp` or `ArrowDown` | Moves focus one week back or forward. |
| `PageUp` or `PageDown` | Moves focus one month, keeping the day where it exists: 31 January goes to 28 February. |
| `Shift+PageUp` or `Shift+PageDown` | Moves focus one year. |
| `Home` or `End` | Moves focus to the first or last day of the week, following `weekStartsOn`. |
| `Enter` or `Space` | Picks the focused day. Disabled days do nothing. |
| `Tab` | Moves through the preset buttons, the previous and next month buttons, then the days. All grids share one tab stop. |

## Accessibility

- Each month is a `role="grid"` named by its month and year, with weekday column headers labelled by the full day name. In range and multiple mode the grid has `aria-multiselectable`.
- Each day is a `<button>` whose `aria-label` is the full date from `Intl.DateTimeFormat`, such as "Saturday, November 14, 2026". Picked days and days inside a finished range set `aria-selected` on their cell, today has `aria-current="date"`, and disabled days have `aria-disabled` but stay focusable.
- Only one day has `tabIndex=0`: the last focused day, else the selection, else today, else the 1st of the first month shown. Arrow keys stop at `min` and `max`, and days from neighbouring months are never a tab stop.
- Month changes are announced by a visually hidden `aria-live="polite"` region. The month slides with the snappy spring, which becomes an instant swap under `useReducedMotion`.

## FAQ

### How do I build a date range picker with Calendar?

Set `mode="range"`. `onValueChange` receives `{ from, to }`, and `to` stays `undefined` until the second click; a click before `from` restarts the range on that day, and a click after a finished range starts a new one. For a field that opens a calendar, put it in a [`Popover`](https://ui.minidev.pro/docs/popover) with a `Button` trigger.

### Does a range skip disabled days?

No. `disabled`, `min` and `max` stop a day from being clicked, but a range from 3 to 10 November still contains a disabled 7 November. If a gap must not be crossed, such as a booked night, check the range in `onValueChange` before you store it.

### How do I use Calendar with React Hook Form or a plain form?

Calendar has no `name` and renders no input, so `FormData` will not see it. With React Hook Form, wrap it in a `Controller` and pass `value={field.value}` and `onValueChange={field.onChange}`. For a native date field use [`DatePicker`](https://ui.minidev.pro/docs/date-picker); [`DateTimePicker`](https://ui.minidev.pro/docs/date-time-picker) takes a `name` and submits an ISO string.

### Why is the calendar empty in the server HTML?

Today depends on the visitor's clock, so Calendar reads it only in the browser: with no `value`, `defaultValue` or `defaultMonth`, the server renders an empty box of the same size and the browser fills it in. Pass `defaultMonth` to get days in the server HTML. `locale` defaults to `"en-US"` for the same reason; pass the user's locale and `weekStartsOn={1}` where Monday comes first.

## Rules for generating code

- Use semantic tokens only (bg, surface, sunken, border, fg, fg-muted, fg-subtle, ink, accent, success, warning, danger). Never raw hex or palette steps like blue-500.
- Shadows only from the set: shadow-xs, shadow-sm, shadow-raised, shadow-md, shadow-lg, shadow-overlay.
- Numbers use tabular-nums. Dark mode is the `dark` class on <html>; components never branch on theme.

## Dependencies

- npm: `lucide-react`, `motion`
- Built from: [button](https://ui.minidev.pro/docs/button/md)

## Related

- [Popover](https://ui.minidev.pro/docs/popover/md): A floating React panel anchored to a trigger, built on Base UI with side and align options, collision aware positioning, title and description parts.
- [Date Picker](https://ui.minidev.pro/docs/date-picker/md): Date picker built on the native date input, styled to match the rest of your form fields. Returns ISO date strings and supports disabled and labelled states.
- [Date Range Picker](https://ui.minidev.pro/docs/date-range-picker/md): Start and end date range picker made from two labelled date inputs. Works controlled or uncontrolled and returns a from and to object for filters and reports.
- [Date Time Picker](https://ui.minidev.pro/docs/date-time-picker/md): React date and time picker in one popover: a calendar and a scrollable time list, 5 to 30 minute steps, past times disabled and a 12 or 24 hour clock.
- [Event Calendar](https://ui.minidev.pro/docs/event-calendar/md): React week and day event calendar: events placed by time, side by side overlaps, an all-day row, a live time line and click or keyboard to create events.
- [Autocomplete](https://ui.minidev.pro/docs/autocomplete/md): Text input that filters string options as you type, using ARIA combobox and listbox roles. Works controlled or uncontrolled and lists up to eight matches.

---

All 557 components: https://ui.minidev.pro/llms.txt (full text: https://ui.minidev.pro/llms-full.txt).
