Date & Time

Users can select dates and times in different contexts across Vista. The Date & Time pattern ensures users are presented with a consistent UI regardless of the type of date they select or the specific page navigated to. This pattern covers the most common scenarios but is not intended to be comprehensive. If you have a unique use case, reach out to us so we can track its usage for future iterations of this pattern.

Need help with copy? Check out the Date and Time Content Guidelines.

GuidelinesScenarios

Use the Date & Time pattern...

For specific timestamping: when users need to select a specific calendar date or timestamp to complete an action.
For scheduling and availability: when the selection depends on external factors like business hours, shipping windows, or appointment slots.

Don't use the Date & Time pattern...

For simple date or time selections - when there is a need for only one component. Use Date Picker, Date Calendar, or Time Picker.

Overview

The Date & Time pattern is a modular framework utilizing SWAN components. You should compose the pieces based on your specific user flow.

1. Heading and description (option)

For the heading, use a font skin that corresponds with the visual hierarchy of the page. The description provides additional context for the task that needs to be completed. Both are optional depending on the scenario.

2. Selection Component(s)

This element or elements initiate the date and/or time selection. It can be a single component, like a DateCalendar, or a combination of them, such as a DatePicker and a TimePicker used together.

Layout

Sequencing

Structure the layout so the date component is primary to the time component in the reading order. This ensures that the time component remains logically and functionally dependent on the date selected.

Spacing

If used outside of a Form (where spacing is already applied), use semantic space between-subsections to put space between the components.

Selection components

Choose between a DatePicker and a DateCalendar based on your page layout. In scenarios where both are feasible, prioritize the DatePicker. It is more versatile, as it supports both manual text entry and calendar selection within a more compact vertical space .

Date Picker & Time Picker

() => {
  // Initialize the date/time
  const [selectedDate, setSelectedDate] = React.useState(
    new Date('2026-01-01T15:00:00Z'),
  )

  // Generate a memoized time options list for the selected date
  const timeOptions = React.useMemo(
    () =>
      selectedDate
        ? [
            new Date('2026-01-01T15:00:00Z'),
            new Date('2026-01-01T16:00:00Z'),
            new Date('2026-01-01T17:00:00Z'),
          ]
        : [],
    [selectedDate],
  )

  // Define a callback for updating the date
  const handleDateChange = newDate => {
    setSelectedDate(newDate)
  }

  // Define a callback for updating the time
  const handleTimeChange = time => {
    setSelectedDate(new Date(time))
  }

  return (
    <GridContainer>
      <Row>
        <Column span={6}>
          <Box mb="between-subsections">
            <H3>Select date and time</H3>
            <Typography>
              Optional description text that is preamble to the date and time
              components. Might give a recommendation of the task needed to be
              achieved.
            </Typography>
          </Box>
          <StandardForm>
            <FormField>
              <FormLabel>Pick a date</FormLabel>
              <FormInputGroup>
                <DatePicker
                  selectedDate={selectedDate}
                  onSelectedDateChange={handleDateChange}
                >
                  <DatePickerInput />
                  <DatePickerPopover>
                    <DatePickerCalendar />
                  </DatePickerPopover>
                </DatePicker>
              </FormInputGroup>
            </FormField>
            <FormField>
              <FormLabel>Pick a time</FormLabel>
              <FormInputGroup>
                <TimePicker
                  fullWidth
                  value={selectedDate ? selectedDate.toISOString() : null}
                  onChange={e => handleTimeChange(e.target.value)}
                >
                  {timeOptions.length > 0 ? (
                    timeOptions.map(time => (
                      <TimePickerOption
                        key={time.toISOString()}
                        value={time.toISOString()}
                        startTime={time}
                      />
                    ))
                  ) : (
                    <TimePickerOption placeholderText="" />
                  )}
                </TimePicker>
              </FormInputGroup>
            </FormField>
          </StandardForm>
        </Column>
      </Row>
    </GridContainer>
  )
}

() => {
  // Initialize the date/time
  const [selectedDate, setSelectedDate] = React.useState(
    new Date('2026-01-01T15:00:00Z'),
  )

  // Generate a memoized time options list for the selected date
  const timeOptions = React.useMemo(
    () =>
      selectedDate
        ? [
            new Date('2026-01-01T15:00:00Z'),
            new Date('2026-01-01T16:00:00Z'),
            new Date('2026-01-01T17:00:00Z'),
          ]
        : [],
    [selectedDate],
  )

  // Define a callback for updating the date
  const handleDateChange = newDate => {
    setSelectedDate(newDate)
  }

  // Define a callback for updating the time
  const handleTimeChange = time => {
    setSelectedDate(new Date(time))
  }

  return (
    <GridContainer>
      <Row>
        <Column span={6}>
          <Box mb="between-subsections">
            <H3>Select date and time</H3>
            <Typography>
              Optional description text that is preamble to the date and time
              components. Might give a recommendation of the task needed to be
              achieved.
            </Typography>
          </Box>
          <StandardForm>
            <FormField>
              <FormLabel>Pick a date</FormLabel>
              <FormInputGroup>
                <DatePicker
                  selectedDate={selectedDate}
                  onSelectedDateChange={handleDateChange}
                >
                  <DatePickerInput />
                  <DatePickerPopover>
                    <DatePickerCalendar />
                  </DatePickerPopover>
                </DatePicker>
              </FormInputGroup>
            </FormField>
            <FormField>
              <FormLabel>Pick a time</FormLabel>
              <FormInputGroup>
                <TimePicker
                  fullWidth
                  value={selectedDate ? selectedDate.toISOString() : null}
                  onChange={e => handleTimeChange(e.target.value)}
                >
                  {timeOptions.length > 0 ? (
                    timeOptions.map(time => (
                      <TimePickerOption
                        key={time.toISOString()}
                        value={time.toISOString()}
                        startTime={time}
                      />
                    ))
                  ) : (
                    <TimePickerOption placeholderText="" />
                  )}
                </TimePicker>
              </FormInputGroup>
            </FormField>
          </StandardForm>
        </Column>
      </Row>
    </GridContainer>
  )
}

Date Calendar & Time Picker

() => {
  // Initialize the date/time
  const [selectedDate, setSelectedDate] = React.useState(
    new Date('2026-01-01T15:00:00Z'),
  )

  // Generate a memoized time options list for the selected date
  const timeOptions = React.useMemo(
    () =>
      selectedDate
        ? [
            new Date('2026-01-01T15:00:00Z'),
            new Date('2026-01-01T16:00:00Z'),
            new Date('2026-01-01T17:00:00Z'),
          ]
        : [],
    [selectedDate],
  )

  // Define a callback for updating the date
  const handleDateChange = newDate => {
    setSelectedDate(newDate)
  }

  // Define a callback for updating the time
  const handleTimeChange = time => {
    setSelectedDate(new Date(time))
  }

  return (
    <GridContainer>
      <Row>
        <Column span={6}>
          <Box mb="between-subsections">
            <H3>Select date and time</H3>
            <Typography>
              Optional description text that is preamble to the date and time
              components. Might give a recommendation of the task needed to be
              achieved.
            </Typography>
          </Box>
          <StandardForm>
            <FormField>
              <FormLabel>Pick a date</FormLabel>
              <FormInputGroup>
                <DateCalendar
                  selectedDate={selectedDate}
                  onSelectedDateChange={handleDateChange}
                />
              </FormInputGroup>
            </FormField>
            <FormField>
              <FormLabel>Pick a time</FormLabel>
              <FormInputGroup>
                <TimePicker
                  fullWidth
                  value={selectedDate ? selectedDate.toISOString() : null}
                  onChange={e => handleTimeChange(e.target.value)}
                >
                  {timeOptions.length > 0 ? (
                    timeOptions.map(time => (
                      <TimePickerOption
                        key={time.toISOString()}
                        value={time.toISOString()}
                        startTime={time}
                      />
                    ))
                  ) : (
                    <TimePickerOption placeholderText="" />
                  )}
                </TimePicker>
              </FormInputGroup>
            </FormField>
          </StandardForm>
        </Column>
      </Row>
    </GridContainer>
  )
}

() => {
  // Initialize the date/time
  const [selectedDate, setSelectedDate] = React.useState(
    new Date('2026-01-01T15:00:00Z'),
  )

  // Generate a memoized time options list for the selected date
  const timeOptions = React.useMemo(
    () =>
      selectedDate
        ? [
            new Date('2026-01-01T15:00:00Z'),
            new Date('2026-01-01T16:00:00Z'),
            new Date('2026-01-01T17:00:00Z'),
          ]
        : [],
    [selectedDate],
  )

  // Define a callback for updating the date
  const handleDateChange = newDate => {
    setSelectedDate(newDate)
  }

  // Define a callback for updating the time
  const handleTimeChange = time => {
    setSelectedDate(new Date(time))
  }

  return (
    <GridContainer>
      <Row>
        <Column span={6}>
          <Box mb="between-subsections">
            <H3>Select date and time</H3>
            <Typography>
              Optional description text that is preamble to the date and time
              components. Might give a recommendation of the task needed to be
              achieved.
            </Typography>
          </Box>
          <StandardForm>
            <FormField>
              <FormLabel>Pick a date</FormLabel>
              <FormInputGroup>
                <DateCalendar
                  selectedDate={selectedDate}
                  onSelectedDateChange={handleDateChange}
                />
              </FormInputGroup>
            </FormField>
            <FormField>
              <FormLabel>Pick a time</FormLabel>
              <FormInputGroup>
                <TimePicker
                  fullWidth
                  value={selectedDate ? selectedDate.toISOString() : null}
                  onChange={e => handleTimeChange(e.target.value)}
                >
                  {timeOptions.length > 0 ? (
                    timeOptions.map(time => (
                      <TimePickerOption
                        key={time.toISOString()}
                        value={time.toISOString()}
                        startTime={time}
                      />
                    ))
                  ) : (
                    <TimePickerOption placeholderText="" />
                  )}
                </TimePicker>
              </FormInputGroup>
            </FormField>
          </StandardForm>
        </Column>
      </Row>
    </GridContainer>
  )
}