Skip to content

Design system

Documentation

DesignComponents / Calendar

Components / Calendar

Beta

Calendar

Choose a date or a date range with a keyboard-operable calendar surface.

On this page

Examples

Select one date

Use a date-only value that does not shift across time zones.

September 2026
SunMonTueWedThuFriSat

Calendar with September 24 selected

Select a date range

Choose a start date, then an end date; the range is normalized into chronological order.

September 2026
SunMonTueWedThuFriSat

Calendar with a selected date range

Try the selection mode

Compare a single date with a start/end range.

September 2026
SunMonTueWedThuFriSat

Calendar selection mode playground

When to use

Use Calendar as a date-selection surface or compose it inside DatePicker. Values are date-only ISO strings in YYYY-MM-DD form; they are calendar dates and are not converted between time zones. Range values use { from, to }, with either end nullable while a range is being chosen.

Usage

import { Calendar, type CalendarValue } from "@phuctech/ui/components/calendar";

const [value, setValue] = useState<CalendarValue>("2026-09-24");
<Calendar value={value} onValueChange={setValue} />

API

Component API
PropTypeDefaultDescriptionConstraints
mode"single" | "range""single"Select one day or the start/end of a range.Range values use an object with from and to strings or null.
value / defaultValueCalendarValuenullControlled or initial selection.Use YYYY-MM-DD strings; do not pass timestamps or native Date values.
onValueChange(value: CalendarValue) => void—Called when the person selects a date.The feature owns persistence and validation beyond min/max.
month / defaultMonth / onMonthChangeYYYY-MM-DD / YYYY-MM-DD / (month: string) => voidselected month or todayControls or initializes the visible month using a date-only string.Use one control model; callbacks receive the first day of the new month as YYYY-MM-DD.
min / max / isDateUnavailabledate string / date string / predicate—Disables days outside bounds or rejected by the supplied predicate.Date strings must use YYYY-MM-DD.
locale / weekStartsOnBCP 47 locale / 0–6browser locale / locale first dayFormats month and weekday labels and sets week order.Week starts Sunday if runtime locale week data is unavailable.
disabled / readOnlybooleanfalseDisabled blocks calendar navigation and selection; readOnly permits navigation but prevents selection.Disabled dates remain visible with native disabled semantics.
isDateUnavailable / section props(date: string) => boolean / HTMLSectionElement props—Adds date-specific unavailable rules and native section attributes.The predicate must be synchronous and side-effect free.

Tokens

Component tokens
TokenRoleEffective valueUsage
card / borderCalendar surfaceShared content surfaceMatches Popover and form surfaces.
focus-ring / primaryDay focus and todayShared focus and action rolesShows keyboard focus and distinguishes today from the selected date.

Accessibility

The calendar is a named group with a labeled grid. Tab enters the focused day; arrow keys move by one day or one week, Home and End move within the week, and Page Up/Down changes month (Shift changes year). Disabled dates cannot be selected, and current selection is exposed on each day.

Do and don’t

Do

Keep date-only values as strings and apply business rules in the feature.

Don’t

Convert a date-only value to midnight in a time zone; that can shift its calendar day.