DatePicker

Accessible, theme-aware, dependency-free date picker component for selecting a single date. Designed for predictable behavior, keyboard accessibility, and seamless form integration.

---

Usage

Basic

import { DatePicker } from '@nofinite/nui';

<DatePicker name="dob" />;

Controlled

import { useState } from 'react';
import { DatePicker } from '@nofinite/nui';

const [date, setDate] = useState('2025-09-12');

<DatePicker value={date} onChange={setDate} />;

With constraints

<DatePicker minDate="2020-01-01" maxDate="2030-12-31" />

---

Props

Prop	Type	Default	Description
value	string	—	Controlled selected date (YYYY-MM-DD).
defaultValue	string	—	Initial value when uncontrolled.
onChange	(v: string) => void	—	Called when a date is selected.
minDate	string	—	Minimum selectable date.
maxDate	string	—	Maximum selectable date.
placeholder	string	'Select date'	Placeholder text when no value is selected.
name	string	—	Name for the hidden input (form integration).
locale	string	'en-US'	Locale for month and weekday labels.
id	string	—	ID for the trigger element.
className	string	''	Additional wrapper class names.

---

Behavior Notes

• Uncontrolled after initialization when using defaultValue

• Value format is always normalized to YYYY-MM-DD.

• Calendar opens on trigger interaction and closes on:

  • Date selection
  • Outside click
  • Escape key

• minDate and maxDate restrict both mouse and keyboard selection.

---

Accessibility

• Trigger renders as a <button>.

• Uses aria-haspopup="dialog".

• Keyboard navigation supported:

  • Arrow keys
  • PageUp / PageDown
  • Home / End

• Enter selects a date.

• Escape closes the calendar.

• Focus is trapped while the calendar is open.

---

Layout

• Trigger is inline-block by default.
• Calendar overlay is positioned relative to the trigger.
• Respects prefers-reduced-motion.

<DatePicker className="w-full" />

---

Styling

No visual variants are exposed via props.

Styling is controlled through CSS variables and class selectors.

Common classes:

• .ui-datepicker
• .ui-datepicker-trigger
• .ui-datepicker-calendar
• .ui-datepicker-day
• .ui-datepicker-day--selected

---

Best Practices

Do

• Use minDate and maxDate to prevent invalid input.
• Prefer controlled usage for validated forms.
• Set locale explicitly for internationalized apps.

Don’t

• Rely on the date picker as the only validation layer.
• Disable keyboard navigation.
• Place inside scroll-trapped containers.