Date picker

A typed date field with a calendar to choose from, and a time when needed.

Import

import { DatePicker } from '@oztix/roadie-components/date-picker'

Examples

Default

Type a date, as in DateField, or press the calendar button and choose a day. Focus the empty field for hints at what can be typed, such as Tomorrow or In 2 weeks, and as you type, the first suggestion is highlighted so Enter takes it. The calendar opens on the chosen day, or on today, with focus on it. Choosing a day closes it and puts focus back on the button. The value is a plain ISO date such as '2026-11-27', or null.

function Default() {
  const [date, setDate] = useState(null)
  return (
    <>
      <DatePicker aria-label='Show date' value={date} onValueChange={setDate} />
      <p className='text-sm text-subtle'>Value: {date ?? 'none'}</p>

Variants

granularity='minute' adds a TimeField beside the date. The value is then the instant the date and time name in timeZone, with its offset, such as '2026-11-27T19:30:00+11:00', and it stays null until both are filled in. Pass the venue's zone, so a Perth organiser setting doors for a Melbourne show sets them on Melbourne's clock. A time that daylight saving skips, such as 2:30am on the morning the clocks go forward, moves to where it lands, 3:30am, and the field shows it.

function Doors() {
  const [doors, setDoors] = useState('2026-11-27T19:30:00+11:00')
  return (
    <>
      <Field>
        <Field.Label>Doors, Melbourne time</Field.Label>

Emphasis

<DatePicker aria-label='Normal' defaultValue='2026-11-27' />
<DatePicker aria-label='Subtle' emphasis='subtle' defaultValue='2026-11-27' />

Sizes

The calendar button shrinks with the field, so it always sits inside it.

<DatePicker aria-label='Small' size='sm' defaultValue='2026-11-27' />
<DatePicker aria-label='Medium' size='md' defaultValue='2026-11-27' />
<DatePicker aria-label='Large' size='lg' defaultValue='2026-11-27' />

States

readOnly shows the date and turns off the calendar button. disabled turns off both.

{/* Default */}
<DatePicker aria-label='Default' defaultValue='2026-11-27' />
{/* Invalid */}
<DatePicker aria-label='Invalid' defaultValue='2026-11-27' invalid />
{/* Read only */}
<DatePicker aria-label='Read only' defaultValue='2026-11-27' readOnly />

Composition

With Field

Wrap it in Field. The label points at the date input, and Field.ErrorText says why typed text isn't a date or a time. At minute granularity the date and time sit in a group named by the label.

<Field required className='max-w-64'>
  <Field.Label showIndicator>Show date</Field.Label>
  <DatePicker placeholder='14 Mar or next Fri' />
  <Field.HelperText>Type a date or choose one</Field.HelperText>
  <Field.ErrorText />
</Field>

With disabled days

disabled takes the same matchers as Calendar. Matched days are disabled in the calendar and refused when typed. Here Raffia Spaceship runs on Fridays and Saturdays in November.

<Field className='max-w-64'>
  <Field.Label>Raffia Spaceship night</Field.Label>
  <DatePicker
    disabled={[
      { before: '2026-11-01' },
      { after: '2026-11-30' },

With a date of birth

captionLayout='dropdown' swaps the month name for month and year selects, for dates far from today. Most people will type a date of birth, but the selects help those who don't.

<Field className='max-w-64'>
  <Field.Label>Date of birth</Field.Label>
  <DatePicker
    captionLayout='dropdown'
    startMonth='1920-01-01'
    endMonth='2012-12-31'

Guidelines

<DatePicker
  granularity='minute'
  timeZone={venue.timeZone}
/>

<DatePicker granularity='minute' />

Accessibility

• The date is a combobox, a text input with suggestions, labelled by Field.Label or aria-label. The calendar button is named after the picker and its date, such as "Choose date, Fri 27 Nov 2026, Doors", and the popup "Choose date, Doors", so pickers side by side stay apart.
• On a screen narrower than 48rem, the calendar opens in a bottom Drawer instead of a popover. Screen readers announce a dialog with the same name. Its title is the picker's label, days grow to fill the width up to 48px, a swipe sideways over the days turns the month, and Close, Escape, a tap outside or a swipe down closes it.
• At minute granularity the date and the time are a group named by the label, with inputs named "Date" and "Time".
• Opening the calendar moves focus to the chosen day, or to today. Arrow keys, Page Up, Page Down, Home and End move as in Calendar. Enter or Space chooses the focused day and closes it. Escape closes it without a change. Either way focus goes back to the button, so on a phone the keyboard doesn't open.
• Focusing the empty date opens hints with nothing highlighted, so Enter still submits the form. Once you type, the first suggestion is highlighted and Enter takes it. The arrow keys move through the list, and Escape closes it and keeps the text. On a phone the list opens under the field, above the page.
• With no suggestion highlighted, Enter commits typed text instead of submitting the form, and Escape puts back the last date.
• With a name, a hidden input submits the value, so a form never receives the formatted text. A disabled picker submits nothing.