Date picker
DraftA calendar-based input for selecting a single date or date range with a dropdown calendar popover.
- Usage
- Specs
- Content
- Status & changelog
- Code
Common alternative names
Calendar, date selector, date input
Usage guidelines coming soon.
Specs coming soon.
Content guidelines coming soon.
Status & changelog coming soon.
Usage
Date Picker renders a text input that opens a calendar popover on focus or click. Users can type a date directly or select one from the calendar grid.
import { DatePicker } from '@arch-ui/components';
function Example() {
const [date, setDate] = React.useState(null);
return (
<DatePicker
value={date}
onChange={setDate}
placeholder="Select a date"
/>
);
}
Date range
Select a start and end date for range-based use cases like booking or filtering.
<DatePicker
range
value={[startDate, endDate]}
onChange={([start, end]) => {
setStartDate(start);
setEndDate(end);
}}
/>
Min and max dates
Constrain the selectable range to prevent invalid selections.
<DatePicker
value={date}
onChange={setDate}
minDate={new Date('2024-01-01')}
maxDate={new Date('2024-12-31')}
/>
Expected props
| Prop | Type | Default | Description |
|---|---|---|---|
value | Date | null | null | The currently selected date. |
onChange | (date: Date | null) => void | undefined | Called when the selected date changes. |
range | boolean | false | Enables date range selection. |
minDate | Date | undefined | Earliest selectable date. |
maxDate | Date | undefined | Latest selectable date. |
placeholder | string | 'Select a date' | Placeholder text in the input trigger. |
disabled | boolean | false | Disables the entire picker. |
size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | Size variant for the input trigger. |
error | boolean | false | Shows an error border style. |
formatString | string | 'yyyy/MM/dd' | Date format string for the input display. |
Accessibility
- The calendar grid should use
role="grid"withrole="gridcell"for each day. - Arrow keys navigate between days, months, and years within the calendar.
- The input trigger should announce the selected date to screen readers.
- Escape closes the popover and returns focus to the input.
- Dates outside the min/max range should be marked with
aria-disabled.
Best practices
Do:
- Use Date Picker when users need to select a specific calendar date.
- Provide
minDateandmaxDateto prevent out-of-range selections. - Allow direct keyboard entry in the text input for power users.
Don't:
- Do not use Date Picker for time-only selection -- use Time Picker instead.
- Do not use Date Picker for selecting relative dates like "last 7 days" -- use a dropdown with predefined ranges.