Skip to content

Design system

Documentation

DesignComponents / DatePicker

Components / DatePicker

Beta

DatePicker

Choose a date or date range using date-only ISO strings and a locale-aware calendar.

On this page

Examples

Single date

Keep a date-only ISO value in feature state and use locale-aware display text.

Invoice date

Controlled invoice date picker

Date range

Choose a start and end date while preserving date-only values.

Reporting period

Controlled reporting-period picker

Try the props

Change the date and test a disabled control.

Invoice date

DatePicker property playground

When to use

Use DatePicker when a form needs a calendar date or date range. Single values are YYYY-MM-DD; range values are { from, to }. These strings represent calendar dates and do not undergo time-zone conversion. Display uses the browser locale unless a locale is supplied.

Usage

import { DatePicker } from "@phuctech/ui/components/date-picker";

<DatePicker label="Invoice date" name="invoiceDate" defaultValue="2026-09-24" />

API

Component API
PropTypeDefaultDescriptionConstraints
mode"single" | "range""single"Selects one date or a start/end range.Range mode expects a CalendarValue range object.
value / defaultValueCalendarValuenullControlled or initial selected value.Single mode uses YYYY-MM-DD; range mode uses { from, to }.
onValueChange(value: CalendarValue) => void—Reports each selected date or range update.The consumer owns business validation and saving.
month / defaultMonth / onMonthChangeYYYY-MM-DD / YYYY-MM-DD / (month: string) => voidselected month or todayControls or initializes the calendar month.Values are date-only strings; callbacks receive the first day of the month.
min / max / isDateUnavailabledate string / date string / predicate—Passes availability rules through to Calendar.Bounds and predicate values use YYYY-MM-DD.
localestringbrowser localeFormats the visible selected date and calendar labels.Use a BCP 47 locale tag.
disabled / readOnly / invalid / requiredbooleanfalseCommunicates unavailable, view-only, invalid, or required states.required is exposed accessibly; the containing form owns native validation.
namestring—Adds hidden form values; range mode uses name[from] and name[to].The feature should still validate the selected value before submission.
label / placeholder / aria-labelstring— / Choose date / mode-specific nameNames the control and supplies empty text.Give the control a visible label or an explicit aria-label.
open / defaultOpen / onOpenChangeboolean / boolean / callbackuncontrolled closedControls popover visibility.Use one controlled or uncontrolled visibility model.

Tokens

Component tokens
TokenRoleEffective valueUsage
input / border / focus-ringPicker triggerShared form-control rolesKeeps the trigger consistent with Input and Button.
popover / elevation-popoverCalendar surfaceShared overlay rolesSeparates the date grid from surrounding form content.

Accessibility

The trigger exposes an accessible name that combines the visible label and selected value, or the supplied aria-label. The calendar supports the same arrow, Home/End, and Page Up/Down navigation as Calendar. Read-only mode permits browsing but not selection.

Do and don’t

Do

Keep date-only values as strings and let the feature decide whether a range is valid.

Don’t

Store a date-only choice as a UTC timestamp and format it in another time zone.

  • Calendar is the reusable selection surface.
  • TimePicker selects a time without a date.
  • Field composes labels and validation messages around controls.