DatePicker

A date picker combines a segmented date input field with a dropdown calendar popup. Users can type a date directly into the field using the keyboard, or open the calendar to select a date visually.

Import

import { DatePicker } from '@proyecto-viviana/solid-spectrum';
import { CalendarDateClass as CalendarDate } from '@proyecto-viviana/solid-stately';

Basic Usage

A simple date picker with a label. Click the calendar icon or focus the field and press the arrow keys to interact with date segments.

Selected: None

const [selectedDate, setSelectedDate] = createSignal<DateValue | null>(null);

<DatePicker
  label="Event date"
  value={selectedDate()}
  onChange={setSelectedDate}
/>

<p>Selected: {selectedDate()?.toString() ?? "None"}</p>

With Min/Max Constraints

Restrict the selectable range by setting minValue and maxValue. The calendar popup will not allow navigation beyond these bounds, and the date segments enforce the limits.

Selected: None

const minDate = new CalendarDate(2026, 1, 1);
const maxDate = new CalendarDate(2026, 6, 30);

<DatePicker
  label="First half of 2026"
  minValue={minDate}
  maxValue={maxDate}
  value={constrainedDate()}
  onChange={setConstrainedDate}
  description="Select a date between Jan 1 and Jun 30, 2026"
/>

Disabled State

A disabled date picker cannot be interacted with. The input field and calendar button are visually muted.

<DatePicker
  label="Disabled date"
  isDisabled
  placeholderValue={new CalendarDate(2026, 3, 15)}
/>

Required with Validation

Mark the date picker as required and provide an error message for invalid states. The field displays a red border and the error text below.

<DatePicker
  label="Birth date"
  isRequired
  isInvalid
  errorMessage="Please select your birth date"
/>

Props

Prop	Type	Default	Description
`label`	string	—	Label text displayed above the date input
`value`	DateValue \| null	—	The currently selected date (controlled)
`onChange`	(date: DateValue \| null) => void	—	Handler called when the selected date changes
`minValue`	DateValue	—	The minimum selectable date
`maxValue`	DateValue	—	The maximum selectable date
`isDisabled`	boolean	`false`	Whether the date picker is disabled
`placeholderValue`	DateValue	—	A placeholder date that controls the default segments shown when empty
`isRequired`	boolean	`false`	Whether a date selection is required
`isInvalid`	boolean	`false`	Whether the date picker is in an invalid state
`errorMessage`	string	—	Error message displayed below the input when invalid
`description`	string	—	Help text displayed below the input
`size`	'sm' \| 'md' \| 'lg'	`'md'`	The visual size of the date picker

Accessibility

Date segments are individually focusable with spinbutton role for screen readers
Arrow Up/Down increments or decrements the focused segment value
Tab moves between date segments (month, day, year)
The calendar popup button has an aria-label describing its purpose
Error messages are associated via aria-describedby for screen reader announcement
Required state is communicated through aria-required
Calendar popup traps focus and can be dismissed with Escape