Date Picker | Components

Use Date Picker...

To prompt users for a date or range with their choice of input field or calendar grid.

Don't use Date Picker...

In scenarios or layouts more suited for a standalone calendar grid. Use DateCalendar instead.

<StandardForm>
  <FormField>
    <FormLabel>Select a date</FormLabel>
    <FormInputGroup>
      <DatePicker>
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>Select a date</FormLabel>
    <FormInputGroup>
      <DatePicker>
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

Selection Mode

Indicates whether the user can select a single date or a range of dates.

Single

Use selectionMode="single" to allow only one date to be entered or selected. This is the default mode.

<StandardForm>
  <FormField>
    <FormLabel>Select a date</FormLabel>
    <FormInputGroup>
      <DatePicker selectionMode="single">
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>Select a date</FormLabel>
    <FormInputGroup>
      <DatePicker selectionMode="single">
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

Range

Use selectionMode="range" to allow a date range to be entered or selected.

<StandardForm>
  <FormField>
    <FormLabel>Select a date range</FormLabel>
    <FormInputGroup>
      <DatePicker selectionMode="range">
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>Select a date range</FormLabel>
    <FormInputGroup>
      <DatePicker selectionMode="range">
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

Disabled

Use disabled to prevent the input field and popover from being focused or selected. If possible, use a message to explain why input/selection is not allowed.

<StandardForm>
  <FormField>
    <FormLabel>Select an appointment date</FormLabel>
    <FormInputGroup>
      <DatePicker defaultDate={new Date(2026, 0, 1)} disabled>
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
      <FormHelper>Your appointment date can no longer be changed.</FormHelper>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>Select an appointment date</FormLabel>
    <FormInputGroup>
      <DatePicker defaultDate={new Date(2026, 0, 1)} disabled>
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
      <FormHelper>Your appointment date can no longer be changed.</FormHelper>
    </FormInputGroup>
  </FormField>
</StandardForm>

Min and max dates

Use minDate, maxDate , or both to narrow the date/range selection to a specific window. The calendar will disable any dates occurring before the minDate and after the maxDate, preventing them from being focused or selected. It will also prevent forward/backward navigation using the arrow controls when there are no available dates in the adjacent months.

<StandardForm>
  <FormField>
    <FormLabel>Select a date</FormLabel>
    <FormInputGroup>
      <DatePicker minDate={new Date(2025, 0, 1)} maxDate={new Date(2025, 0, 4)}>
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
  <FormField>
    <FormLabel>Select a date range</FormLabel>
    <FormInputGroup>
      <DatePicker
        selectionMode="range"
        minDate={new Date(2025, 0, 1)}
        maxDate={new Date(2025, 0, 4)}
      >
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>Select a date</FormLabel>
    <FormInputGroup>
      <DatePicker minDate={new Date(2025, 0, 1)} maxDate={new Date(2025, 0, 4)}>
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
  <FormField>
    <FormLabel>Select a date range</FormLabel>
    <FormInputGroup>
      <DatePicker
        selectionMode="range"
        minDate={new Date(2025, 0, 1)}
        maxDate={new Date(2025, 0, 4)}
      >
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

Unavailable dates

Use isDateUnavailable to provide a callback that evaluates whether each visible date is unavailable for selection. A date is “unavailable” when it is not selectable, but may be preceded or followed by other selectable dates (e.g. preventing weekends from being selected while still allowing weekdays).

Non-contiguous ranges

By default, non-contiguous date ranges are allowed. This means that any range can be selected even if an unavailable date would fall in the middle.

() => {
  // Weekends are unavailable
  const isDateUnavailable = date => {
    const day = date.getDay()
    return day === 0 || day === 6
  }

  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a shipping window</FormLabel>
        <FormInputGroup>
          <DatePicker
            selectionMode="range"
            isDateUnavailable={isDateUnavailable}
            defaultRange={{
              start: new Date(2025, 0, 1),
              end: new Date(2025, 0, 10),
            }}
          >
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
          <FormHelper>
            In this example, non-contiguous date ranges are allowed (which is
            the default behavior). This means that any range can be selected
            even if an unavailable date would fall in the middle.
          </FormHelper>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

() => {
  // Weekends are unavailable
  const isDateUnavailable = date => {
    const day = date.getDay()
    return day === 0 || day === 6
  }

  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a shipping window</FormLabel>
        <FormInputGroup>
          <DatePicker
            selectionMode="range"
            isDateUnavailable={isDateUnavailable}
            defaultRange={{
              start: new Date(2025, 0, 1),
              end: new Date(2025, 0, 10),
            }}
          >
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
          <FormHelper>
            In this example, non-contiguous date ranges are allowed (which is
            the default behavior). This means that any range can be selected
            even if an unavailable date would fall in the middle.
          </FormHelper>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

Contiguous ranges

Use allowsNonContiguousRanges={false} to prevent non-contiguous ranges from being selected. This means that a range cannot be selected if an unavailable date is in the middle. On selection of a start date, the calendar will disable any end dates that would result in an unavailable date falling in the middle of the range.

() => {
  // Weekends are unavailable
  const isDateUnavailable = date => {
    const day = date.getDay()
    return day === 0 || day === 6
  }

  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a shipping window</FormLabel>
        <FormInputGroup>
          <DatePicker
            selectionMode="range"
            isDateUnavailable={isDateUnavailable}
            allowsNonContiguousRanges={false}
            defaultRange={{
              start: new Date(2025, 0, 6),
              end: new Date(2025, 0, 10),
            }}
          >
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
          <FormHelper>
            In this example, non-contiguous date ranges are not allowed. This
            means that a range cannot be selected if an unavailable date is in
            the middle. On selection of a start date, notice how the calendar
            updates to disable any end dates that would result in an unavailable
            date in the middle of the range.
          </FormHelper>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

() => {
  // Weekends are unavailable
  const isDateUnavailable = date => {
    const day = date.getDay()
    return day === 0 || day === 6
  }

  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a shipping window</FormLabel>
        <FormInputGroup>
          <DatePicker
            selectionMode="range"
            isDateUnavailable={isDateUnavailable}
            allowsNonContiguousRanges={false}
            defaultRange={{
              start: new Date(2025, 0, 6),
              end: new Date(2025, 0, 10),
            }}
          >
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
          <FormHelper>
            In this example, non-contiguous date ranges are not allowed. This
            means that a range cannot be selected if an unavailable date is in
            the middle. On selection of a start date, notice how the calendar
            updates to disable any end dates that would result in an unavailable
            date in the middle of the range.
          </FormHelper>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

Labels, errors, and helper text

Use the Form Field components to incorporate labels, error messages, or helper text. These components automatically apply the necessary ARIA attributes to the Date Picker, eliminating the need for manual handling.

With Form components (preferred)

() => {
  const [selectedDate, setSelectedDate] = React.useState(null)
  const maxDate = new Date()
  const invalid = selectedDate ? selectedDate > maxDate : false

  return (
    <StandardForm>
      <FormField>
        <FormLabel>What is your birthday?</FormLabel>
        <FormInputGroup>
          <DatePicker
            selectedDate={selectedDate}
            onSelectedDateChange={setSelectedDate}
            maxDate={maxDate}
          >
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
          <FormHelper>Hint: Your birthday must be in the past.</FormHelper>
          {invalid && (
            <FormError>Your birthday can't be in the future, silly!</FormError>
          )}
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

() => {
  const [selectedDate, setSelectedDate] = React.useState(null)
  const maxDate = new Date()
  const invalid = selectedDate ? selectedDate > maxDate : false

  return (
    <StandardForm>
      <FormField>
        <FormLabel>What is your birthday?</FormLabel>
        <FormInputGroup>
          <DatePicker
            selectedDate={selectedDate}
            onSelectedDateChange={setSelectedDate}
            maxDate={maxDate}
          >
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
          <FormHelper>Hint: Your birthday must be in the past.</FormHelper>
          {invalid && (
            <FormError>Your birthday can't be in the future, silly!</FormError>
          )}
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

Without Form components

Labels

Use aria-labelledby (preferred) or a localized aria-label prop to provide an accessible label.

<FlexBox flexDirection="column" gap={4}>
  <>
    <Typography fontSkin="body-standard-bold">
      With aria-labelledby (preferred)
    </Typography>
    <Typography id="date-picker-label">Select a date</Typography>
    <DatePicker aria-labelledby="date-picker-label">
      <DatePickerInput />
      <DatePickerPopover>
        <DatePickerCalendar />
      </DatePickerPopover>
    </DatePicker>
  </>
  <Divider my={4} />
  <>
    <Typography fontSkin="body-standard-bold">With aria-label</Typography>
    <DatePicker aria-label="Select a date">
      <DatePickerInput />
      <DatePickerPopover>
        <DatePickerCalendar />
      </DatePickerPopover>
    </DatePicker>
  </>
</FlexBox>

<FlexBox flexDirection="column" gap={4}>
  <>
    <Typography fontSkin="body-standard-bold">
      With aria-labelledby (preferred)
    </Typography>
    <Typography id="date-picker-label">Select a date</Typography>
    <DatePicker aria-labelledby="date-picker-label">
      <DatePickerInput />
      <DatePickerPopover>
        <DatePickerCalendar />
      </DatePickerPopover>
    </DatePicker>
  </>
  <Divider my={4} />
  <>
    <Typography fontSkin="body-standard-bold">With aria-label</Typography>
    <DatePicker aria-label="Select a date">
      <DatePickerInput />
      <DatePickerPopover>
        <DatePickerCalendar />
      </DatePickerPopover>
    </DatePicker>
  </>
</FlexBox>

Errors

Use aria-errormessage and aria-describedby to provide an accessible error message, and use skin=”error” on DatePickerInput to apply a red border.

() => {
  const today = new Date()
  const tomorrow = new Date(today)
  tomorrow.setDate(today.getDate() + 1)

  const [selectedDate, setSelectedDate] = React.useState(tomorrow)
  const invalid = selectedDate ? selectedDate > today : false

  return (
    <>
      <Typography id="date-picker-label">What is your birthday?</Typography>
      <DatePicker
        selectedDate={selectedDate}
        onSelectedDateChange={setSelectedDate}
        aria-errormessage="error-text"
        aria-describedby="error-text"
        aria-labelledby="date-picker-label"
      >
        <DatePickerInput skin={invalid ? 'error' : undefined} />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
      {invalid && (
        <Span textColor="error" id="error-text">
          Your birthday can't be in the future, silly!
        </Span>
      )}
    </>
  )
}

() => {
  const today = new Date()
  const tomorrow = new Date(today)
  tomorrow.setDate(today.getDate() + 1)

  const [selectedDate, setSelectedDate] = React.useState(tomorrow)
  const invalid = selectedDate ? selectedDate > today : false

  return (
    <>
      <Typography id="date-picker-label">What is your birthday?</Typography>
      <DatePicker
        selectedDate={selectedDate}
        onSelectedDateChange={setSelectedDate}
        aria-errormessage="error-text"
        aria-describedby="error-text"
        aria-labelledby="date-picker-label"
      >
        <DatePickerInput skin={invalid ? 'error' : undefined} />
        <DatePickerPopover>
          <DatePickerCalendar />
        </DatePickerPopover>
      </DatePicker>
      {invalid && (
        <Span textColor="error" id="error-text">
          Your birthday can't be in the future, silly!
        </Span>
      )}
    </>
  )
}

Helper text

Use aria-describedby to provide accessible helper text.

<>
  <Typography id="range-picker-label">Select a shipping window</Typography>
  <DatePicker
    selectionMode="range"
    aria-describedby="range-picker-description"
    aria-labelledby="range-picker-label"
  >
    <DatePickerInput />
    <DatePickerPopover>
      <DatePickerCalendar />
    </DatePickerPopover>
  </DatePicker>
  <Span fontSkin="footnote" id="range-picker-description">
    Shipping delays may occur
  </Span>
</>

<>
  <Typography id="range-picker-label">Select a shipping window</Typography>
  <DatePicker
    selectionMode="range"
    aria-describedby="range-picker-description"
    aria-labelledby="range-picker-label"
  >
    <DatePickerInput />
    <DatePickerPopover>
      <DatePickerCalendar />
    </DatePickerPopover>
  </DatePicker>
  <Span fontSkin="footnote" id="range-picker-description">
    Shipping delays may occur
  </Span>
</>

Calendar shortcuts

Today

Use showTodayButton on DatePickerCalendar to reveal a “Today” button that updates the calendar to reflect the current month. This option is best to use in scenarios where the user's selected date is far from the present. Note that today’s date will NOT be selected or focused.

<StandardForm>
  <FormField>
    <FormLabel>Select a date</FormLabel>
    <FormInputGroup>
      <DatePicker>
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar showTodayButton />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>Select a date</FormLabel>
    <FormInputGroup>
      <DatePicker>
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar showTodayButton />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

Clear

Use showClearButton on DatePickerCalendar to reveal a “Clear” button that clears the currently selected date or date range.

<StandardForm>
  <FormField>
    <FormLabel>Select a date</FormLabel>
    <FormInputGroup>
      <DatePicker>
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar showClearButton />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>Select a date</FormLabel>
    <FormInputGroup>
      <DatePicker>
        <DatePickerInput />
        <DatePickerPopover>
          <DatePickerCalendar showClearButton />
        </DatePickerPopover>
      </DatePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

Managing state

Single

Controlled

Use selectedDate to provide a stored value and onSelectedDateChange to provide a callback for managing that value. The callback will be invoked whenever the date is edited by the user.

() => {
  const [date, setDate] = React.useState(new Date(2026, 0, 1))
  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a date (controlled)</FormLabel>
        <FormInputGroup>
          <DatePicker selectedDate={date} onSelectedDateChange={setDate}>
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

() => {
  const [date, setDate] = React.useState(new Date(2026, 0, 1))
  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a date (controlled)</FormLabel>
        <FormInputGroup>
          <DatePicker selectedDate={date} onSelectedDateChange={setDate}>
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

Uncontrolled

Omit selectedDate and onSelectedDateChange to allow the browser to manage the state. Use defaultDate to provide an initial value.

() => {
  const date = new Date(2025, 0, 1)

  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a date (uncontrolled)</FormLabel>
        <FormInputGroup>
          <DatePicker defaultDate={date}>
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

() => {
  const date = new Date(2025, 0, 1)

  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a date (uncontrolled)</FormLabel>
        <FormInputGroup>
          <DatePicker defaultDate={date}>
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

Range

Controlled

Use selectedRange to provide a stored value and onSelectedRangeChange to provide a callback for managing that value. The callback will be invoked only when the end date is edited by the user.

() => {
  const [range, setRange] = React.useState({
    start: new Date(2025, 0, 1),
    end: new Date(2025, 0, 31),
  })
  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a date range (controlled)</FormLabel>
        <FormInputGroup>
          <DatePicker
            selectionMode="range"
            selectedRange={range}
            onSelectedRangeChange={setRange}
          >
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

() => {
  const [range, setRange] = React.useState({
    start: new Date(2025, 0, 1),
    end: new Date(2025, 0, 31),
  })
  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a date range (controlled)</FormLabel>
        <FormInputGroup>
          <DatePicker
            selectionMode="range"
            selectedRange={range}
            onSelectedRangeChange={setRange}
          >
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

Uncontrolled

Omit selectedRange and onSelectedRangeChange to allow the browser to manage the state. Use defaultRange to provide an initial value.

() => {
  const range = {
    start: new Date(2025, 0, 1),
    end: new Date(2025, 0, 31),
  }

  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a date range (uncontrolled)</FormLabel>
        <FormInputGroup>
          <DatePicker selectionMode="range" defaultRange={range}>
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

() => {
  const range = {
    start: new Date(2025, 0, 1),
    end: new Date(2025, 0, 31),
  }

  return (
    <StandardForm>
      <FormField>
        <FormLabel>Select a date range (uncontrolled)</FormLabel>
        <FormInputGroup>
          <DatePicker selectionMode="range" defaultRange={range}>
            <DatePickerInput />
            <DatePickerPopover>
              <DatePickerCalendar />
            </DatePickerPopover>
          </DatePicker>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

Internationalization

Month names, weekday names, placeholder format, the first day of the week, and other locale-specific features are automatically formatted using the locale provided to the SWAN I18n Provider and according to our Date/Time content guidelines.

Accessibility

A DatePicker must have an accessible label that describes the purpose of the date selection. Refer to Labels, errors, and helper text.