Time Picker | Components

Use Time Picker...

To select a time within a traditional form.

Don't use Time Picker...

To display data types that aren't times. Use a Dropdown, Listbox, or Menu instead.

Time Picker is built using Dropdown, which uses the native HTML select element, so the appearance of its Dropdown list is determined by the user's browser and device.

Time Picker is a specialized Dropdown component that automatically formats JavaScript Date objects according to the locale provided to the SWAN Ii18n Provider using our Date/Time content guidelines.

Time slot

Use startTime and endTime on TimePickerOption to display a time slot.

<TimePicker aria-label="Example with a time slot">
  <TimePickerOption
    value="A"
    startTime={new Date('2026-02-02T10:30:00Z')}
    endTime={new Date('2026-02-02T11:00:00Z')}
  />
  <TimePickerOption
    value="B"
    startTime={new Date('2026-02-02T14:45:00Z')}
    endTime={new Date('2026-02-02T15:00:00Z')}
  />
  <TimePickerOption
    value="C"
    startTime={new Date('2026-02-02T22:00:00Z')}
    endTime={new Date('2026-02-02T23:00:00Z')}
  />
</TimePicker>

<TimePicker aria-label="Example with a time slot">
  <TimePickerOption
    value="A"
    startTime={new Date('2026-02-02T10:30:00Z')}
    endTime={new Date('2026-02-02T11:00:00Z')}
  />
  <TimePickerOption
    value="B"
    startTime={new Date('2026-02-02T14:45:00Z')}
    endTime={new Date('2026-02-02T15:00:00Z')}
  />
  <TimePickerOption
    value="C"
    startTime={new Date('2026-02-02T22:00:00Z')}
    endTime={new Date('2026-02-02T23:00:00Z')}
  />
</TimePicker>

Single time

Use startTime only to display a single time option.

<TimePicker aria-label="Example with a single time">
  <TimePickerOption value="A" startTime={new Date('2026-02-02T10:30:00Z')} />
  <TimePickerOption value="B" startTime={new Date('2026-02-02T14:45:00Z')} />
  <TimePickerOption value="C" startTime={new Date('2026-02-02T22:00:00Z')} />
</TimePicker>

<TimePicker aria-label="Example with a single time">
  <TimePickerOption value="A" startTime={new Date('2026-02-02T10:30:00Z')} />
  <TimePickerOption value="B" startTime={new Date('2026-02-02T14:45:00Z')} />
  <TimePickerOption value="C" startTime={new Date('2026-02-02T22:00:00Z')} />
</TimePicker>

Full width

Use fullWidth to grow a TimePicker to fill its container.

<TimePicker aria-label="Example using full width" fullWidth>
  <TimePickerOption
    value="A"
    startTime={new Date('2026-02-02T10:30:00Z')}
    endTime={new Date('2026-02-02T11:00:00Z')}
  />
  <TimePickerOption
    value="B"
    startTime={new Date('2026-02-02T14:45:00Z')}
    endTime={new Date('2026-02-02T15:00:00Z')}
  />
  <TimePickerOption
    value="C"
    startTime={new Date('2026-02-02T22:00:00Z')}
    endTime={new Date('2026-02-02T23:00:00Z')}
  />
</TimePicker>

<TimePicker aria-label="Example using full width" fullWidth>
  <TimePickerOption
    value="A"
    startTime={new Date('2026-02-02T10:30:00Z')}
    endTime={new Date('2026-02-02T11:00:00Z')}
  />
  <TimePickerOption
    value="B"
    startTime={new Date('2026-02-02T14:45:00Z')}
    endTime={new Date('2026-02-02T15:00:00Z')}
  />
  <TimePickerOption
    value="C"
    startTime={new Date('2026-02-02T22:00:00Z')}
    endTime={new Date('2026-02-02T23:00:00Z')}
  />
</TimePicker>

With floating label

Use InputWithFloatingLabel to display a Time Picker with the label positioned inside of it, above the selection.

<InputWithFloatingLabel>
  <FloatingLabel>Pick a time</FloatingLabel>
  <TimePicker>
    <TimePickerOption
      value="A"
      startTime={new Date('2026-02-02T10:30:00Z')}
      endTime={new Date('2026-02-02T11:00:00Z')}
    />
    <TimePickerOption
      value="B"
      startTime={new Date('2026-02-02T14:45:00Z')}
      endTime={new Date('2026-02-02T15:00:00Z')}
    />
    <TimePickerOption
      value="C"
      startTime={new Date('2026-02-02T22:00:00Z')}
      endTime={new Date('2026-02-02T23:00:00Z')}
    />
  </TimePicker>
</InputWithFloatingLabel>

<InputWithFloatingLabel>
  <FloatingLabel>Pick a time</FloatingLabel>
  <TimePicker>
    <TimePickerOption
      value="A"
      startTime={new Date('2026-02-02T10:30:00Z')}
      endTime={new Date('2026-02-02T11:00:00Z')}
    />
    <TimePickerOption
      value="B"
      startTime={new Date('2026-02-02T14:45:00Z')}
      endTime={new Date('2026-02-02T15:00:00Z')}
    />
    <TimePickerOption
      value="C"
      startTime={new Date('2026-02-02T22:00:00Z')}
      endTime={new Date('2026-02-02T23:00:00Z')}
    />
  </TimePicker>
</InputWithFloatingLabel>

Disabled

Use disabled on TimePicker to prevent it from being opened. For example, disable TimePicker until the user selects a date.

Use disabled on TimePickerOption to indicate that individual options are not relevant or available within the user’s current context.

<FlexBox flexWrap="wrap" gap="between-actions">
  <Box>
    <TimePicker aria-label="Example using disabled on time picker" disabled>
      <TimePickerOption
        value="A"
        startTime={new Date('2026-02-02T10:30:00Z')}
        endTime={new Date('2026-02-02T11:00:00Z')}
      />
      <TimePickerOption
        value="B"
        startTime={new Date('2026-02-02T14:45:00Z')}
        endTime={new Date('2026-02-02T15:00:00Z')}
      />
      <TimePickerOption
        value="C"
        startTime={new Date('2026-02-02T22:00:00Z')}
        endTime={new Date('2026-02-02T23:00:00Z')}
      />
    </TimePicker>
  </Box>
  <Box>
    <TimePicker aria-label="Example using disabled on time picker option">
      <TimePickerOption
        value="A"
        startTime={new Date('2026-02-02T10:30:00Z')}
        endTime={new Date('2026-02-02T11:00:00Z')}
      />
      <TimePickerOption
        disabled
        value="B"
        startTime={new Date('2026-02-02T14:45:00Z')}
        endTime={new Date('2026-02-02T15:00:00Z')}
      />
      <TimePickerOption
        value="C"
        startTime={new Date('2026-02-02T22:00:00Z')}
        endTime={new Date('2026-02-02T23:00:00Z')}
      />
    </TimePicker>
  </Box>
</FlexBox>

<FlexBox flexWrap="wrap" gap="between-actions">
  <Box>
    <TimePicker aria-label="Example using disabled on time picker" disabled>
      <TimePickerOption
        value="A"
        startTime={new Date('2026-02-02T10:30:00Z')}
        endTime={new Date('2026-02-02T11:00:00Z')}
      />
      <TimePickerOption
        value="B"
        startTime={new Date('2026-02-02T14:45:00Z')}
        endTime={new Date('2026-02-02T15:00:00Z')}
      />
      <TimePickerOption
        value="C"
        startTime={new Date('2026-02-02T22:00:00Z')}
        endTime={new Date('2026-02-02T23:00:00Z')}
      />
    </TimePicker>
  </Box>
  <Box>
    <TimePicker aria-label="Example using disabled on time picker option">
      <TimePickerOption
        value="A"
        startTime={new Date('2026-02-02T10:30:00Z')}
        endTime={new Date('2026-02-02T11:00:00Z')}
      />
      <TimePickerOption
        disabled
        value="B"
        startTime={new Date('2026-02-02T14:45:00Z')}
        endTime={new Date('2026-02-02T15:00:00Z')}
      />
      <TimePickerOption
        value="C"
        startTime={new Date('2026-02-02T22:00:00Z')}
        endTime={new Date('2026-02-02T23:00:00Z')}
      />
    </TimePicker>
  </Box>
</FlexBox>

Time zone

Use timeZone on TimePicker to designate an IANA time zone.

The browser will automatically detect and apply the user’s timezone, so this prop is only necessary if you need to override the user’s timezone.

Additionally, the user’s timezone will be unknown when a Time Picker is rendered on the server. See our guidelines on server-side rendering [update link on docsite] to avoid hydration issues.

<TimePicker aria-label="Example using time zone" timeZone="America/New_York">
  <TimePickerOption
    value="A"
    startTime={new Date('2026-02-02T10:30:00Z')}
    endTime={new Date('2026-02-02T11:00:00Z')}
  />
  <TimePickerOption
    value="B"
    startTime={new Date('2026-02-02T14:45:00Z')}
    endTime={new Date('2026-02-02T15:00:00Z')}
  />
  <TimePickerOption
    value="C"
    startTime={new Date('2026-02-02T22:00:00Z')}
    endTime={new Date('2026-02-02T23:00:00Z')}
  />
</TimePicker>

<TimePicker aria-label="Example using time zone" timeZone="America/New_York">
  <TimePickerOption
    value="A"
    startTime={new Date('2026-02-02T10:30:00Z')}
    endTime={new Date('2026-02-02T11:00:00Z')}
  />
  <TimePickerOption
    value="B"
    startTime={new Date('2026-02-02T14:45:00Z')}
    endTime={new Date('2026-02-02T15:00:00Z')}
  />
  <TimePickerOption
    value="C"
    startTime={new Date('2026-02-02T22:00:00Z')}
    endTime={new Date('2026-02-02T23:00:00Z')}
  />
</TimePicker>

Placeholder text

Use placeholderText with TimePickerOption to display text instead of a formatted time. This can be useful if you don’t want the first time to be preselected.

If value is not passed to the TimePickerOption, the value will default to the placeholderText.'

<TimePicker aria-label="Example using placeholder text">
  <TimePickerOption placeholderText="Pick a time..." />
  <TimePickerOption
    value="A"
    startTime={new Date('2026-02-02T10:30:00Z')}
    endTime={new Date('2026-02-02T11:00:00Z')}
  />
  <TimePickerOption
    value="B"
    startTime={new Date('2026-02-02T14:45:00Z')}
    endTime={new Date('2026-02-02T15:00:00Z')}
  />
  <TimePickerOption
    value="C"
    startTime={new Date('2026-02-02T22:00:00Z')}
    endTime={new Date('2026-02-02T23:00:00Z')}
  />
</TimePicker>

<TimePicker aria-label="Example using placeholder text">
  <TimePickerOption placeholderText="Pick a time..." />
  <TimePickerOption
    value="A"
    startTime={new Date('2026-02-02T10:30:00Z')}
    endTime={new Date('2026-02-02T11:00:00Z')}
  />
  <TimePickerOption
    value="B"
    startTime={new Date('2026-02-02T14:45:00Z')}
    endTime={new Date('2026-02-02T15:00:00Z')}
  />
  <TimePickerOption
    value="C"
    startTime={new Date('2026-02-02T22:00:00Z')}
    endTime={new Date('2026-02-02T23:00:00Z')}
  />
</TimePicker>

Labels, errors, and helper text

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

<StandardForm>
  <FormField>
    <FormLabel>Select a time</FormLabel>
    <FormInputGroup>
      <TimePicker>
        <TimePickerOption
          value="A"
          startTime={new Date('2026-02-02T10:30:00Z')}
          endTime={new Date('2026-02-02T11:00:00Z')}
        />
        <TimePickerOption
          value="B"
          startTime={new Date('2026-02-02T14:45:00Z')}
          endTime={new Date('2026-02-02T15:00:00Z')}
        />
        <TimePickerOption
          value="C"
          startTime={new Date('2026-02-02T22:00:00Z')}
          endTime={new Date('2026-02-02T23:00:00Z')}
        />
      </TimePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>Select a time</FormLabel>
    <FormInputGroup>
      <TimePicker>
        <TimePickerOption
          value="A"
          startTime={new Date('2026-02-02T10:30:00Z')}
          endTime={new Date('2026-02-02T11:00:00Z')}
        />
        <TimePickerOption
          value="B"
          startTime={new Date('2026-02-02T14:45:00Z')}
          endTime={new Date('2026-02-02T15:00:00Z')}
        />
        <TimePickerOption
          value="C"
          startTime={new Date('2026-02-02T22:00:00Z')}
          endTime={new Date('2026-02-02T23:00:00Z')}
        />
      </TimePicker>
    </FormInputGroup>
  </FormField>
</StandardForm>

Managing state

Controlled

Use value and onChange on TimePicker to provide a stored value and callback for managing that value. The callback will be invoked whenever a selection is changed by the user.

() => {
  const [selectedValue, setSelectedValue] = React.useState('A')
  return (
    <TimePicker
      aria-label="Example with controlled state"
      value={selectedValue}
      onChange={event => setSelectedValue(event.target.value)}
    >
      <TimePickerOption
        value="A"
        startTime={new Date('2026-01-01T10:30:00Z')}
        endTime={new Date('2026-01-01T11:00:00Z')}
      />
      <TimePickerOption
        value="B"
        startTime={new Date('2026-01-01T11:00:00Z')}
        endTime={new Date('2026-01-01T11:30:00Z')}
      />
      <TimePickerOption
        value="C"
        startTime={new Date('2026-01-01T11:30:00Z')}
        endTime={new Date('2026-01-01T12:00:00Z')}
      />
    </TimePicker>
  )
}

() => {
  const [selectedValue, setSelectedValue] = React.useState('A')
  return (
    <TimePicker
      aria-label="Example with controlled state"
      value={selectedValue}
      onChange={event => setSelectedValue(event.target.value)}
    >
      <TimePickerOption
        value="A"
        startTime={new Date('2026-01-01T10:30:00Z')}
        endTime={new Date('2026-01-01T11:00:00Z')}
      />
      <TimePickerOption
        value="B"
        startTime={new Date('2026-01-01T11:00:00Z')}
        endTime={new Date('2026-01-01T11:30:00Z')}
      />
      <TimePickerOption
        value="C"
        startTime={new Date('2026-01-01T11:30:00Z')}
        endTime={new Date('2026-01-01T12:00:00Z')}
      />
    </TimePicker>
  )
}

Uncontrolled

Omit value and onChange to allow the browser to handle the state. Use defaultValue on TimePicker to specify the initial selected value.

<TimePicker aria-label="Example with controlled state" defaultValue={'B'}>
  <TimePickerOption
    value="A"
    startTime={new Date('2026-01-01T10:30:00Z')}
    endTime={new Date('2026-01-01T11:00:00Z')}
  />
  <TimePickerOption
    value="B"
    startTime={new Date('2026-01-01T11:00:00Z')}
    endTime={new Date('2026-01-01T11:30:00Z')}
  />
  <TimePickerOption
    value="C"
    startTime={new Date('2026-01-01T11:30:00Z')}
    endTime={new Date('2026-01-01T12:00:00Z')}
  />
</TimePicker>

<TimePicker aria-label="Example with controlled state" defaultValue={'B'}>
  <TimePickerOption
    value="A"
    startTime={new Date('2026-01-01T10:30:00Z')}
    endTime={new Date('2026-01-01T11:00:00Z')}
  />
  <TimePickerOption
    value="B"
    startTime={new Date('2026-01-01T11:00:00Z')}
    endTime={new Date('2026-01-01T11:30:00Z')}
  />
  <TimePickerOption
    value="C"
    startTime={new Date('2026-01-01T11:30:00Z')}
    endTime={new Date('2026-01-01T12:00:00Z')}
  />
</TimePicker>

Server-side rendering

To avoid issues with hydration across time zones and locales, you should render Time Picker components as empty initially, then populate them with times after SSR. This can be done using a combination of React’s useState and useEffect hooks.

() => {
  const [times, setTimes] = React.useState(null)
  React.useEffect(() => {
    setTimes([
      new Date('2026-01-01T10:30:00'),
      new Date('2026-01-01T14:45:00'),
      new Date('2026-01-01T22:00:00'),
    ])
  }, [])
  return (
    <TimePicker aria-label="Example with server-side rendering">
      {times?.map(time => (
        <TimePickerOption
          key={time.toTimeString()}
          value={time.toTimeString()}
          startTime={time}
        />
      ))}
    </TimePicker>
  )
}

() => {
  const [times, setTimes] = React.useState(null)
  React.useEffect(() => {
    setTimes([
      new Date('2026-01-01T10:30:00'),
      new Date('2026-01-01T14:45:00'),
      new Date('2026-01-01T22:00:00'),
    ])
  }, [])
  return (
    <TimePicker aria-label="Example with server-side rendering">
      {times?.map(time => (
        <TimePickerOption
          key={time.toTimeString()}
          value={time.toTimeString()}
          startTime={time}
        />
      ))}
    </TimePicker>
  )
}

Accessibility

See accessibility details for Forms.