Design System/Atoms/Calendar

Calendar

A date selection component built on react-day-picker v9. Supports single dates, ranges, multiple months, and custom disabled states.

When To Use

  • Use Calendar when the user needs to enter or choose information as part of a larger form or workflow.
  • Start from this pattern when you need the interaction, spacing, and state treatment to match the rest of the system.
  • Use the examples below to choose the least complex control that still communicates the user’s next step clearly.

When Not To Use

  • Do not introduce a heavier or more customizable control when a simpler native-style field is sufficient.
  • Do not hide required context, validation, or option meaning behind placeholder text alone.

Accessibility Notes

  • Keep a visible label or an equivalent accessible name attached to the control.
  • Surface validation and helper text programmatically so assistive technologies receive the same context as sighted users.
  • Preserve the native focus order and keyboard interactions instead of replacing them with custom behavior.

Key Props / API

Composition surface

Calendar keeps the native HTML or Radix API surface, then layers in design-system styling and composition defaults.

Example Code

import { Calendar } from "@hilum/ui"

const [date, setDate] = React.useState<Date | undefined>()

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

Calendar · Single

Single date selection

Pick a single date with click. Selected date highlighted in brand orange.

May 2026

No date selected

Calendar · Range

Range selection

Click a start and end date to select a range.

May 2026

From: — · To: —

Calendar · Multiple Months

Two months side by side

Set numberOfMonths={2} to display a multi-month calendar.

May 2026
June 2026

No date selected

Calendar · Disabled Dates

Disabled weekends

Pass a matcher function to disabled to block specific dates.

May 2026

Weekends are unavailable