---
name: date-picker-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit DatePicker
for locale-aware segmented date entry, calendar selection, optional
transactional time entry, single or range typed values, and canonical form
serialization through one integrated field.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux zag-compound-components app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: "https://zagjs.com/components/react/date-input https://zagjs.com/components/react/date-picker https://react-aria.adobe.com/internationalized/date/"
contributor_sources: "libs/ui/src/molecules/date-picker.tsx libs/ui/src/tokens/components/molecules/_date-picker.css libs/ui/stories/molecules/date-picker.stories.tsx"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit DatePicker Usage
Use DatePicker when a user should type a locale-aware date in segments or pick
it from a calendar. Set `granularity` to `hour`, `minute`, or `second` when the
same field must also collect a time. Use separate domain controls when date and
time have independent lifecycles.
## Shared field contract
Use canonical `sm`, `md` (default), and `lg`. Compose `DatePicker.StatusText`
under the root to associate helper/error text with every focusable date segment.
Each message gets a unique ID; caller segment descriptions are preserved, errors
set `aria-invalid` and `aria-errormessage`, and non-neutral feedback has an icon.
Read-only preserves focusable, copyable date segments and submitted values while
hiding calendar/clear actions and preventing all commits. Activating read-only or
disabled while a calendar is open closes it and discards its draft. Read-only is
not a calendar browsing mode. Popup positioner and content use the shared layer.
Footer actions keep secondary Cancel before primary Confirm.
If read-only is enabled while the calendar owns focus, the popup closes without
committing its draft and focus returns to a surviving date segment. Focus already
moved to another control is not stolen.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `DatePicker`.
**Use it when**
- Entering a specific date or date-time: delivery date, publish schedule, birth date, report period.
- When users benefit from both typing (segments) and picking (calendar).
**Use something else when**
| Need | Use instead |
| --- | --- |
| Showing a date (read-only) | formatted text via `Intl.DateTimeFormat` |
| Relative choices (`Last 7 days`, `This month`) | Select or RadioGroup of presets, optionally with a custom range |
| Time-of-day only with an independent lifecycle | a separate time control |
**Do**
- Pass the app `locale` explicitly — the component defaults to `en-US`, NumericInput to `cs-CZ` (ux-guidelines/formatting#locale-defaults-in-the-kit).
- Set `min`/`max` and unavailable dates so impossible choices can't be made, and say why in help text (`Delivery from 2 working days`).
- Use `granularity` for date-time instead of two unrelated fields when they form one value.
- Show the time zone when it matters (scheduled publishing, cut-offs).
**Don't**
- Add a hand-written format hint that disagrees with the locale's segment order.
- Use a calendar for birth dates far in the past without allowing typing.
- Store or display ISO strings to users.
**Copy and states**
- Label names the date's meaning (`Delivery date`, `Publish at`), not `Date`.
- Validation says the allowed range in formatted dates: `Choose a date between 4 Sept 2026 and 30 Sept 2026.`
**Behaviour (from the UX spec)**
- Changing the month or year only changes the view; it never confirms a day or completes a range.
- Today, selected and unavailable days look different, not by colour alone; today is never treated as the selected value.
- In timed range mode, start and end times are named separately, and an overnight range is validated with its dates, not only the clock order.
**Figma → code**
| Figma | Code |
| --- | --- |
| `state=error` | `invalid` + `DatePicker.StatusText` |
| `state=readonly` | `readOnly` |
| `datepicker-periodview` (`view=month` / `year`) | the calendar heading's views; not a part |
| `datepicker-calendarday` states | rendered by `DatePicker.Calendar` from the value, `min`/`max`, `isDateUnavailable` |
| `datepicker-timecontrol` | `DatePicker.TimeControl` + `Footer` (Cancel, Confirm) |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/DatePicker → UX guidelines*.
## Setup
Date-only selection uses `CalendarDate | null` and commits a calendar choice
immediately:
```tsx
import { CalendarDate } from "@internationalized/date"
import { DatePicker } from "@techsio/ui-kit/molecules/date-picker"
Delivery date
```
Range selection uses a complete readonly tuple. It defaults to two coordinated
months and renders distinct start/end segment groups in the same field:
```tsx
import { CalendarDate } from "@internationalized/date"
import { DatePicker } from "@techsio/ui-kit/molecules/date-picker"
Reporting period
```
Timed selection uses `CalendarDateTime | ZonedDateTime | null`. Include the
time control and transaction footer:
```tsx
import { CalendarDateTime } from "@internationalized/date"
import { DatePicker } from "@techsio/ui-kit/molecules/date-picker"
Appointment
```
## Public Contract
```text
granularity: day | hour | minute | second
selectionMode: single | range
size: sm | md | lg
value/defaultValue:
day -> CalendarDate | null
timed -> CalendarDateTime | ZonedDateTime | null
day range -> readonly [CalendarDate, CalendarDate] | null
timed range -> readonly [CalendarDateTime, CalendarDateTime] | null
| readonly [ZonedDateTime, ZonedDateTime] | null
onValueChange: ({ value, valueAsString }) => void
open/defaultOpen/onOpenChange
locale, timeZone, hourCycle, hideTimeZone, shouldForceLeadingZeros
min, max, startOfWeek, numOfMonths, isDateUnavailable, isTimeUnavailable
disabled, readOnly, invalid, required
DatePicker.Label accepts requiredLabel: screen-reader text for the required state; pass a translation, "" omits it (default "(required)")
single: name, form
range: startName, endName, form
placement, gutter, offset, flip, sameWidth, slide, overflowPadding
```
The `sm`, `md`, and `lg` field sizes follow the shared Input typography and
form-control geometry. `readOnly` keeps the normal field surface while
removing edit and clear affordances. `invalid` uses the same validation border
width and danger-state progression as Input; the normal focus ring remains the
focus indicator.
## Core Patterns
### Keep one typed value shape
Use `CalendarDate` for a calendar date without time. Use `CalendarDateTime` for
a floating wall-clock date-time, or provide a `ZonedDateTime` explicitly when
the zone is part of the domain value. Do not pass Zag's internal arrays or a
native JavaScript `Date`.
Range mode uses only complete two-value tuples. A one-ended range is private
input/calendar state and never appears in `value`, `onValueChange`, or form
serialization. Timed tuples must contain two floating `CalendarDateTime`
values or two `ZonedDateTime` values; never mix the kinds.
```tsx
const [value, setValue] = useState(null)
setValue(details.value)}
>
{/* canonical date-only compound parts */}
```
`timeZone` controls presentation and calendar calculations. It does not turn a
floating `CalendarDateTime` into a zoned value.
Date-only range selection commits after the second valid endpoint. The first
endpoint stays private and the popup remains open. `numOfMonths` defaults to
two in range mode and one in single mode.
A start endpoint typed into the segments stays private until the end endpoint
is complete. Opening the calendar discards that partial segment draft; closing
the calendar keeps it. A complete calendar range replaces it. Clicking or
tabbing into the segments closes an open calendar at once; when a controlled
parent refuses that close, a half-picked calendar range is kept.
### Select neighboring-month days
Muted days at the beginning or end of a calendar grid remain selectable and
navigate that panel to the selected month. They obey the same `min`, `max`,
`isDateUnavailable`, disabled, and read-only rules as other days. Muted does not
mean disabled; unavailable days also have a strike-through.
### Edit popup times with the keyboard
Hour, minute, and second inputs accept typing. ArrowUp/ArrowDown increment or
decrement by one and wrap within the field (0–23 or 1–12 hours, 0–59 minutes
and seconds); Home/End select the field minimum/maximum. Wrapping does not
change the calendar date or AM/PM. Select AM/PM separately in 12-hour mode.
Keyboard edits remain drafts until Confirm, just like pointer edits.
### Treat timed popups as transactions
In `hour`, `minute`, and `second` modes, calendar and time edits stay private
until Confirm. Cancel, Escape, outside dismissal, and trigger dismissal discard
the draft. The main segments continue to show the accepted value and become
read-only while the popup is open.
Timed range mode follows the same single transaction for both endpoints.
`DatePicker.TimeControl` renders separate Start time and End time groups, while
one Cancel/Confirm footer accepts or discards the whole interval.
Its hour, minute, second, and day-period fields intentionally keep the compact
`sm` control density at every DatePicker root size so the calendar remains the
primary surface.
The first day selected in an empty timed picker is intentionally incomplete.
Enter the required time before Confirm becomes available. Do not add app-side
callbacks that treat intermediate popup edits as committed values.
### Let a controlled parent remain authoritative
`onValueChange` proposes only a committed value. A controlled parent may
accept, reject, delay, or transform it; render the `value` prop as the source of
truth. If `value` changes externally while a timed draft is open, DatePicker
resynchronizes the draft to that accepted value.
### Use the root-owned form value
Set `name` in single mode. Set explicit `startName` and `endName` in range
mode. The root renders one or two hidden form controls from the accepted value.
Serialization is `DateValue.toString()` and never localized display text:
```text
CalendarDate -> 2026-08-31
CalendarDateTime -> 2026-08-31T14:30:00
ZonedDateTime -> offset- and zone-preserving string
null -> empty string
range null -> two empty strings
```
Do not add another hidden input with the same name. An unnamed native validation proxy participates in required validation, including incomplete segments, and routes invalid-submission focus to the first editable/incomplete segment. Disabled and read-only fields are exempt. Application/server validation is still required.
### Preserve the accessible compound anatomy
Use one `DatePicker.Label`, then Control with Segments and the trigger group.
Keep Content inside Positioner. In timed modes, keep TimeControl and the
Cancel/Confirm footer inside Content. The high-level Segments, Calendar, and
TimeControl parts preserve the private Zag Date Input and Date Picker wiring.
Use meaningful label text. The default Clear, Calendar, Cancel, and Confirm
trigger labels are accessible; replace their children only with equally clear
content or an accessible name.
Required editable segments expose `aria-required`. Pass `aria-describedby` to
`DatePicker.Segments` when external help or validation text describes the
compound field.
## Non-Goals
The 1.1 API does not support multiple dates, presets, quick ranges, month-only
selection, custom date-cell rendering, raw Zag anatomy, a custom serializer,
public partial ranges, or native `Date` values. Do not build those behaviors by
reaching through the compound component's internals.
## Common Mistakes
### HIGH Separate custom date and time controls
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/molecules/date-picker.tsx
### HIGH Native Date or incomplete/mixed range
Wrong:
```tsx
```
Correct:
```tsx
```
Source: https://react-aria.adobe.com/internationalized/date/
### HIGH Committing timed popup edits outside Confirm
Wrong:
```tsx
```
Correct:
```tsx
```
There is no public draft callback in the 1.1 contract.
### HIGH Duplicate form ownership
Wrong:
```tsx
{/* parts */}
```
Correct:
```tsx
{/* parts */}
```
In range mode, use `startName` and `endName` instead of `name`.
## Validation Commands
```sh
rg -n ']*type="(date|datetime-local|time)"|new Date\(' apps
rg -n ']*(onDraftValueChange|closeOnSelect|commitMode)' apps
rg -n ']*selectionMode="range"[^>]*name=' apps
rg -U -P -n ']*name=(?![\s\S]{0,900}