calendar

Philosophy

Calendars are complex accessibility challenges disguised as simple grids. We own the entire calendar stack - from the headless engine (@gentleduck/calendar) to the compound primitives (@gentleduck/primitives/calendar) to this styled component. The adapter pattern lets you swap date libraries, the hook layer handles state management, and this component applies Tailwind styling via data-* attribute selectors.

How It's Built

Installation

npx @gentleduck/cli add calendar

npx @gentleduck/cli add calendar

Usage

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

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

const [date, setDate] = React.useState<Date | undefined>(new Date())
 
return (
  <Calendar
    mode="single"
    selected={date}
    onSelect={setDate}
    className="rounded-lg border"
  />
)

const [date, setDate] = React.useState<Date | undefined>(new Date())
 
return (
  <Calendar
    mode="single"
    selected={date}
    onSelect={setDate}
    className="rounded-lg border"
  />
)

See the @gentleduck/calendar package docs for more information on the headless engine, date adapters, and advanced features.

Examples

Date Picker (Popover)

Date Picker (Input)

Date Input (Natural Language)

Form Integration

Multi-Month Range Picker

Range Calendar

Date Constraints

Multi-Select

Event Calendar

Custom Cell Size

Click to View Events (Popover)

Booked Dates (Strikethrough)

Booking Calendar

Multi-Range Selection

Multi-Range with Shift+Click

Presets

Persian (Jalali) Calendar

Islamic (Hijri) Calendar

Hebrew Calendar

Hebrew Calendar (English)

Islamic Calendar (English)

Persian Calendar (English)

Notes

Blocks

We have built a collection of 30+ calendar blocks that you can use to build your own calendar components.

See all calendar blocks in the Blocks Library page.

Migrated from react-day-picker

Date Picker

You can use the <Calendar> component to build a date picker. See the Date Picker page for more information.

RTL Support

Direction is resolved through the shared primitives direction module. Use a local dir="rtl" override when the component exposes it, or set DirectionProvider at app/root level for global RTL/LTR behavior.

Motion

Use MotionCalendar for smooth month navigation transitions and staggered day cell entry powered by motion. The grid slides directionally when navigating months, and day cells fade in with a stagger effect.

API Reference

Calendar

Render Props

The Calendar component exposes render props that let you customize every visual part without forking the component.

renderDay

Customize the content inside each day cell. Receives the Grid.ICalendarDay object and the default children (the date number).

<Calendar
  renderDay={(day, children) => (
    <>
      {children}
      {hasEvents(day.date) && (
        <span className="size-1 rounded-full bg-primary" />
      )}
    </>
  )}
/>

<Calendar
  renderDay={(day, children) => (
    <>
      {children}
      {hasEvents(day.date) && (
        <span className="size-1 rounded-full bg-primary" />
      )}
    </>
  )}
/>

The day object exposes: date, isToday, isSelected, isDisabled, isOutside, isHidden, isWeekend, isRangeStart, isRangeEnd, isRangeMiddle.

renderHeader

Replace the entire navigation header. Receives a context object with navigation controls.

<Calendar
  renderHeader={({ month, title, direction, goToPrevMonth, goToNextMonth, isPrevDisabled, isNextDisabled }) => (
    <div className="flex items-center justify-between px-2">
      <button onClick={goToPrevMonth} disabled={isPrevDisabled}><-</button>
      <span className="font-semibold">{title}</span>
      <button onClick={goToNextMonth} disabled={isNextDisabled}>-></button>
    </div>
  )}
/>

<Calendar
  renderHeader={({ month, title, direction, goToPrevMonth, goToNextMonth, isPrevDisabled, isNextDisabled }) => (
    <div className="flex items-center justify-between px-2">
      <button onClick={goToPrevMonth} disabled={isPrevDisabled}><-</button>
      <span className="font-semibold">{title}</span>
      <button onClick={goToNextMonth} disabled={isNextDisabled}>-></button>
    </div>
  )}
/>

renderWeekday

Customize individual weekday column headers. Receives the abbreviation and column index.

<Calendar
  renderWeekday={(day, index) => (
    <span className={index === 0 || index === 6 ? "text-red-400" : ""}>
      {day}
    </span>
  )}
/>

<Calendar
  renderWeekday={(day, index) => (
    <span className={index === 0 || index === 6 ? "text-red-400" : ""}>
      {day}
    </span>
  )}
/>

renderFooter

Add content below the calendar grid. Receives the current months array for context.

<Calendar
  renderFooter={() => (
    <div className="mt-2 text-xs text-muted-foreground">
      Pick a date to continue
    </div>
  )}
/>

<Calendar
  renderFooter={() => (
    <div className="mt-2 text-xs text-muted-foreground">
      Pick a date to continue
    </div>
  )}
/>

Data Attributes

The calendar uses data-* attributes on day cells for styling. Target these in your CSS:

MotionCalendar

Adds directional slide transitions on month navigation (with blur) and staggered day cell entry animation. Uses LazyMotion for a lightweight bundle (~5KB). Requires the motion package.

CSS Variables