Examples
Single date
Keep a date-only ISO value in feature state and use locale-aware display text.
Controlled invoice date picker
"use client";
import { useState } from "react";
import { DatePicker } from "@phuctech/ui/components/date-picker";
export function Example() {
const [value, setValue] = useState<string | null>("2026-09-24");
return <DatePicker label="Invoice date" value={value} onValueChange={(nextValue) => setValue(typeof nextValue === "string" ? nextValue : null)} name="invoiceDate" />;
}
Date range
Choose a start and end date while preserving date-only values.
Controlled reporting-period picker
"use client";
import { useState } from "react";
import { DatePicker } from "@phuctech/ui/components/date-picker";
import type { CalendarValue } from "@phuctech/ui/components/calendar";
export function Example() {
const [value, setValue] = useState<CalendarValue>({ from: "2026-09-14", to: null });
return <DatePicker mode="range" label="Reporting period" value={value} onValueChange={setValue} name="period" />;
}
Try the props
Change the date and test a disabled control.
DatePicker property playground
import { DatePicker } from "@phuctech/ui/components/date-picker";
export function Example() {
return <DatePicker label="Invoice date" defaultValue="2026-09-24" />;
}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
Tokens
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
Keep date-only values as strings and let the feature decide whether a range is valid.
Store a date-only choice as a UTC timestamp and format it in another time zone.
Related
- Calendar is the reusable selection surface.
- TimePicker selects a time without a date.
- Field composes labels and validation messages around controls.