DatePicker
DatePicker composes Calendar and an anchored overlay into one localizable, form-backed single-date control.
Overview and decision boundary
Use DatePicker for one custom, localizable ISO calendar date when native Input type=date is not sufficient.
Do not add ranges, presets, localized parsing, time, timezone conversion, scheduling, availability, recurrence, or product shortcuts.
Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add date-pickerimport { Field } from "@nerio-ui/ui";import { DatePicker } from "@nerio-ui/ui/client";Usage
import { Field } from "@nerio-ui/ui";import { DatePicker } from "@nerio-ui/ui/client";<Field label="Release date"> <DatePicker defaultValue="2026-06-15" clearable /></Field>Variants
| Contract | Description |
|---|---|
Uncontrolled | Use defaultValue for a complete source-owned form control. |
Controlled | Own value and open state when product composition requires it. |
Clearable | Opt into one explicit clear action; no presets or shortcuts are added. |
Anatomy
| Slot | Description |
|---|---|
root | State wrapper for the trigger, popup, and form mirror. |
trigger | Native button aligned with the form-control family. |
content | Anchored Base UI Popover surface. |
Calendar slots | Calendar retains its complete public anatomy inside the popup. |
clear | Optional explicit action that returns the value to empty. |
form-control | Single hidden native form value mirror. |
States
| State | Behavior |
|---|---|
Empty | Shows the explicit placeholder and open action context. |
Selected | Formats one ISO value for display without changing its submitted value. |
Open | Moves focus into Calendar and restores it after selection or dismissal. |
Invalid | Uses the form-family invalid border and forwards aria-invalid. |
Required | The native form mirror participates in constraint validation. |
Read-only | The popup remains inspectable while value and clear actions are locked. |
Disabled | The trigger and form value are disabled. |
Motion
- Popover uses the shared overlay enter and exit contract.
- Reduced motion keeps dismissal and focus behavior immediate.
Accessibility
- Name the trigger through Field, Label, aria-label, or aria-labelledby.
- A self-named trigger does not repeat its visible value; controls named by Field or explicit ARIA retain the localized selected value once before the open/change action.
- Opening moves focus to Calendar's selected or active roving day; selection, Escape, outside dismissal, and clear restore focus to the trigger.
- The public value and single named form mirror use the timezone-independent YYYY-MM-DD CalendarDate contract; null is the explicit controlled empty value.
- Required, disabled, read-only, invalid, form ownership, submission, and reset behavior remain truthful.
- Locale and formatValue change display only; DatePicker does not parse localized or natural-language text.
- Calendar preserves its complete keyboard, RTL, constraint, forced-colors, reduced-motion, and localization contract.
- Ranges, presets, time, timezone conversion, availability, scheduling, recurrence, and product shortcuts remain outside DatePicker.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Type | Description |
|---|---|---|
value / defaultValue | CalendarDate | null | Controlled or uncontrolled selected YYYY-MM-DD date; null is empty. |
onValueChange | (date | null) => void | Receives selection or an explicit clear. |
open / defaultOpen | boolean | Controlled or uncontrolled Popover state. |
onOpenChange | (open, details) => void | Receives bounded Nerio dismissal details. |
name / form | string | Native form ownership and submitted key. |
onInvalid | FormEventHandler<HTMLInputElement> | Observes native constraint validation. |
required / disabled / readOnly / invalid | boolean | Form and interaction states. |
min / max / isDateDisabled | Calendar contract | Reused Calendar constraints. |
today | CalendarDate | Consumer-owned current date for today styling and empty-state month selection. |
locale / firstDayOfWeek | Intl locale / 0–6 | Display, labels, and week order; locale defaults to en-US for deterministic SSR. |
formatValue | (date, locale) => ReactNode | Strict display formatting only; never parsing. |
placeholder | ReactNode | Explicit empty-state text. |
labels | DatePickerLabels | Localized trigger context, clear, Calendar, and navigation copy. |
clearable | boolean | Adds one explicit clear action when a value exists. |
ref | HTMLElement | Accesses the public trigger control. |
Implementation contract
| Contract | Value |
|---|---|
Entrypoint | @nerio-ui/ui/client |
Value | Timezone-independent ISO YYYY-MM-DD or null. |
Overlay | Base UI Popover with Calendar as the single interactive date surface. |
Form | One native-compatible submitted value with reset and required behavior. |
Registry | nerio add date-picker installs DatePicker, Calendar, Popover styling, and source dependencies. |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use DatePicker for one custom, localizable ISO calendar date when native Input type=date is not sufficient.
Do / do not
Do
- Use native Input type=date when direct keyboard text entry is required.
- Use DatePicker for one custom, localizable calendar date.
- Wrap it in Field or provide an explicit ARIA naming strategy.
Do not
- Parse localized or natural-language text.
- Add ranges, presets, time, timezone, availability, or scheduling.
- Duplicate the form value with another named date input.
Related components
Tokens
| Layer | Tokens | Controls |
|---|---|---|
Form family | --n-input-* | Closed trigger states and density. |
Overlay | --n-overlay-* / --n-popover-* | Anchored popup surface and motion. |
Calendar | --n-calendar-* | Month grid, days, selection, and constraints. |
Focus | --n-focus-ring | Trigger and Calendar focus visibility. |