Calendar

A date picker calendar supporting single date and date range selection.

Examples

Single

May 2026

() => {
  const [value, setValue] = useState<PlainDate | undefined>(() =>
    plainDateCreate(2026, 5, 21),
  );
  return <Calendar onChange={setValue} value={value} />;
}

Right To Left

May 2026

<div dir="rtl">
  <Calendar onChange={() => {}} value={plainDateCreate(2026, 5, 21)} />
</div>

Range

May 2026

() => {
  const [value, setValue] = useState<DateRange | undefined>(() => ({
    start: plainDateCreate(2026, 5, 10),
    end: plainDateCreate(2026, 5, 16),
  }));
  return (
    <Calendar
      mode="range"
      onChange={setValue}
      value={value}
      viewDate={plainDateCreate(2026, 5, 1)}
    />
  );
}

Single Day Range

May 2026

() => {
  const [value, setValue] = useState<DateRange | undefined>(() => ({
    start: plainDateCreate(2026, 5, 5),
    end: plainDateCreate(2026, 5, 5),
  }));
  return (
    <Calendar
      mode="range"
      onChange={setValue}
      value={value}
      viewDate={plainDateCreate(2026, 5, 1)}
    />
  );
}

Two Months

May 2026 - June 2026

() => {
  const [value, setValue] = useState<PlainDate | undefined>(() =>
    plainDateCreate(2026, 5, 21),
  );
  return (
    <Calendar
      numberOfMonths={2}
      onChange={setValue}
      value={value}
      viewDate={plainDateCreate(2026, 5, 1)}
    />
  );
}

With Constraints

May 2026

() => {
  const [value, setValue] = useState<PlainDate | undefined>(() =>
    plainDateCreate(2026, 5, 21),
  );
  return (
    <Calendar
      max={plainDateCreate(2026, 5, 24)}
      min={plainDateCreate(2026, 5, 8)}
      onChange={setValue}
      value={value}
      viewDate={plainDateCreate(2026, 5, 1)}
    />
  );
}

Week Numbers

May 2026

() => {
  const [value, setValue] = useState<PlainDate | undefined>(() =>
    plainDateCreate(2026, 5, 21),
  );
  return (
    <Calendar
      hasWeekNumbers
      onChange={setValue}
      value={value}
      viewDate={plainDateCreate(2026, 5, 1)}
      weekStartsOn={1}
    />
  );
}

Disabled Weekends

May 2026

() => {
  const [value, setValue] = useState<PlainDate | undefined>();
  return (
    <Calendar
      getIsDateDisabled={date => date.dayOfWeek === 6 || date.dayOfWeek === 7}
      onChange={setValue}
      value={value}
      viewDate={plainDateCreate(2026, 5, 1)}
    />
  );
}

Hide Outside Days

May 2026

() => {
  const [value, setValue] = useState<PlainDate | undefined>(() =>
    plainDateCreate(2026, 5, 21),
  );
  return (
    <Calendar
      hasOutsideDays={false}
      onChange={setValue}
      value={value}
      viewDate={plainDateCreate(2026, 5, 1)}
    />
  );
}

Variable Row Count

February 2026

() => {
  const [value, setValue] = useState<PlainDate | undefined>();
  return (
    <Calendar
      hasVariableRowCount
      onChange={setValue}
      value={value}
      viewDate={plainDateCreate(2026, 2, 1)}
    />
  );
}

Range Interactive

May 2026

() => {
  const [value, setValue] = useState<DateRange | undefined>();
  return (
    <Calendar
      mode="range"
      onChange={setValue}
      value={value}
      viewDate={plainDateCreate(2026, 5, 1)}
    />
  );
}

API

Calendar

A date picker calendar supporting single date and date range selection.

When mode: "single"

Prop	Type	Default	Description
`defaultValue`	`PlainDate`	—	Default selected date for uncontrolled usage.
`maxRangeSpan`	`never`	—	Range span constraints are only available in range mode.
`minRangeSpan`	`never`	—	Range span constraints are only available in range mode.
`mode`	`'single'`	—	Selection mode. Defaults to 'single'.
`onChange`*	`(value: PlainDate) => void`	—	Called when the selected date changes.
`value`	`PlainDate`	—	Controlled selected date.
`className`	`string`	—	Additional CSS class names applied to the root element.
`data-testid`	`string`	—	Test ID applied to the root element.
`getIsDateDisabled`	`(date: PlainDate) => boolean`	—	Returns true for dates that should be disabled.
`hasAutoFocus`	`boolean`	`false`	Whether to move focus into the day grid — onto the selected date, otherwise today, otherwise the first enabled day. Focus is (re)applied whenever this transitions to `true`, so driving it from an open state focuses the grid each time the calendar opens.
`hasOutsideDays`	`boolean`	`true`	Whether to show outside-month days.
`hasVariableRowCount`	`boolean`	`false`	Whether month grids use only needed rows rather than a fixed six rows.
`hasWeekNumbers`	`boolean`	`false`	Whether to show ISO week numbers.
`max`	`PlainDate`	—	Maximum selectable date.
`min`	`PlainDate`	—	Minimum selectable date.
`numberOfMonths`	`1 \| 2`	`1`	Number of months displayed.
`onViewDateChange`	`(viewDate: PlainDate) => void`	—	Called when the visible month changes. Passing this alongside `viewDate` puts the visible month in controlled mode: the calendar stops tracking the month itself and renders whatever `viewDate` you feed back here.
`ref`	`Ref<CalendarHandle>`	—	Ref exposing imperative calendar navigation.
`style`	`CSSProperties`	—	Inline styles applied to the root element.
`timezoneID`	`string`	`browser timezone`	Timezone used to determine today's date.
`viewDate`	`PlainDate`	—	The visible month. On its own this is just the initial month to display; the calendar then tracks the month internally. Pass `onViewDateChange` as well to make the visible month controlled, where `viewDate` is the source of truth on every render.
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	`0`	First day of week, where 0 is Sunday.

When mode: "range"

Prop	Type	Default	Description
`defaultValue`	`DateRange`	—	Default selected range for uncontrolled usage.
`maxRangeSpan`	`Temporal.Duration`	—	Maximum duration between the selected range start and end. Must be a non-negative, date-based Temporal duration.
`minRangeSpan`	`Temporal.Duration`	—	Minimum duration between the selected range start and end. Must be a non-negative, date-based Temporal duration.
`mode`*	`'range'`	—	Selection mode set to 'range'.
`onChange`*	`(value: DateRange) => void`	—	Called when the selected date range changes.
`value`	`DateRange`	—	Controlled selected date range.
`className`	`string`	—	Additional CSS class names applied to the root element.
`data-testid`	`string`	—	Test ID applied to the root element.
`getIsDateDisabled`	`(date: PlainDate) => boolean`	—	Returns true for dates that should be disabled.
`hasAutoFocus`	`boolean`	`false`	Whether to move focus into the day grid — onto the selected date, otherwise today, otherwise the first enabled day. Focus is (re)applied whenever this transitions to `true`, so driving it from an open state focuses the grid each time the calendar opens.
`hasOutsideDays`	`boolean`	`true`	Whether to show outside-month days.
`hasVariableRowCount`	`boolean`	`false`	Whether month grids use only needed rows rather than a fixed six rows.
`hasWeekNumbers`	`boolean`	`false`	Whether to show ISO week numbers.
`max`	`PlainDate`	—	Maximum selectable date.
`min`	`PlainDate`	—	Minimum selectable date.
`numberOfMonths`	`1 \| 2`	`1`	Number of months displayed.
`onViewDateChange`	`(viewDate: PlainDate) => void`	—	Called when the visible month changes. Passing this alongside `viewDate` puts the visible month in controlled mode: the calendar stops tracking the month itself and renders whatever `viewDate` you feed back here.
`ref`	`Ref<CalendarHandle>`	—	Ref exposing imperative calendar navigation.
`style`	`CSSProperties`	—	Inline styles applied to the root element.
`timezoneID`	`string`	`browser timezone`	Timezone used to determine today's date.
`viewDate`	`PlainDate`	—	The visible month. On its own this is just the initial month to display; the calendar then tracks the month internally. Pass `onViewDateChange` as well to make the visible month controlled, where `viewDate` is the source of truth on every render.
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	`0`	First day of week, where 0 is Sunday.