Skip to main content

​
Overview

April 2026
Calendar is a standalone month-view grid for selecting a date or date range. It is the underlying component used by DatePicker and DateRangePicker — use Calendar directly when you need an always-visible calendar (not in a popover).
Need a calendar inside a popover trigger? Use DatePicker instead. Calendar is for always-visible inline calendar UIs.

​
Installation

npm install @araf-ds/core

​
Usage

import { Calendar } from "@araf-ds/core"
import { useState } from "react"

export default function Example() {
  const [date, setDate] = useState<Date | undefined>(new Date())

  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
    />
  )
}

​
Variants

​
Single Date Selection

April 2026
const [date, setDate] = useState<Date | undefined>()

<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  initialFocus
/>

​
Date Range Selection

April 2026
const [range, setRange] = useState<DateRange | undefined>()

<Calendar
  mode="range"
  selected={range}
  onSelect={setRange}
  numberOfMonths={2}
/>

​
With Disabled Dates

<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  disabled={[
    { before: new Date() },          // Disable past dates
    { dayOfWeek: [0, 6] },           // Disable weekends
    new Date(2026, 3, 25),           // Disable a specific date
  ]}
/>

​
API Reference

​
mode
string
required
Selection mode. Values: single · multiple · range
​
selected
Date | Date[] | DateRange | undefined
Controlled selected value. Type depends on mode.
​
onSelect
(date) => void
Callback fired when selection changes. Argument type matches mode.
​
defaultMonth
Date
The month shown on initial render.
​
numberOfMonths
number
default:"1"
Number of months to display side by side (useful for range selection).
​
disabled
Matcher | Matcher[]
Rules for disabled dates. Accepts: Date, DateRange, DayOfWeek, Before, After, or a function (date: Date) => boolean.
​
fromDate
Date
The earliest navigable and selectable month.
​
toDate
Date
The latest navigable and selectable month.
​
initialFocus
boolean
default:"false"
Auto-focus the calendar on mount — required when used inside a Dialog or Popover.
​
weekStartsOn
number
default:"0"
Day the week starts on. 0 = Sunday, 1 = Monday.

​
Accessibility

  • Calendar grid uses role="grid" with column headers labeled by weekday abbreviation
  • Each day cell has role="gridcell" with aria-selected and aria-disabled
  • Navigation buttons are labeled “Go to previous month” / “Go to next month”
  • Keyboard: Arrow keys move focus between days, Enter/Space selects, Page Up/Down navigates months

​
Do’s & Don’ts

Do

  • Use initialFocus when placing Calendar inside a Dialog or Popover
  • Use numberOfMonths={2} for range selection to show both start and end months
  • Use disabled prop to prevent selection of past dates, weekends, or holidays
  • Show a clear visual distinction between range start, range middle, and range end

Don't

  • Don’t use Calendar inline inside a form field — use DatePicker instead
  • Don’t display more than 3 months side by side — it becomes too wide on mobile
  • Don’t forget initialFocus in modal contexts — keyboard users will be stuck outside
  • Don’t use mode="multiple" for date ranges — use mode="range" instead