DatePicker

A date picker allows to select a single value from a pre-determined set.

Uncontrolled Value

By default, the DatePicker component handles its value uncontrolled. In the uncontrolled variant you can pass in a defaultValue to set a value by default.

<DatePicker
  label="Date"
  defaultValue={new CalendarDate(2019, 2, 3)}
  data-testid="1"
/>

<DatePicker
  label="Date"
  defaultValue={new CalendarDate(2019, 2, 3)}
  data-testid="1"
/>

<DatePicker
  label="Date"
  defaultValue={new CalendarDate(
    2019,
    2,
    3
  )}
  data-testid="1"
/>

Controlled Value

You can also handle the value of the component in a controlled manner. To do so, you can pass in a value prop as well as an onChange handler to modify the value when the user types.

function Example() {
  const [value, setValue] = useState(new CalendarDate(2019, 2, 3));

  return (
    <div>
      <DatePicker 
        label='Date' 
        value={value} 
        onChange={setValue} 
      />

      <div>Value: {value.toString()}</div>
    </div>
  );
}

function Example() {
  const [value, setValue] = useState(
    new CalendarDate(2019, 2, 3)
  );

  return (
    <div>
      <DatePicker
        label="Date"
        value={value}
        onChange={setValue}
      />

      <div>Value: {value.toString()}</div>
    </div>
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState(
    new CalendarDate(
      2019,
      2,
      3
    )
  );

  return (
    <div>
      <DatePicker
        label="Date"
        value={value}
        onChange={setValue}
      />

      <div>
        Value:{' '}
        {value
          .toString()}
      </div>
    </div>
  );
}

Granularity

The granularity of the DatePicker can be modified through the granularity prop. If you add a granulatiry smaller than day it will automatically display a timefield with the timezone.

<DatePicker label='Date' granularity='millisecond' />
<DatePicker label='Date' granularity='second' />
<DatePicker label='Date' granularity='minute' />
<DatePicker label='Date' granularity='hour' />
<DatePicker label='Date' granularity='day' />

<DatePicker label='Date' granularity='millisecond' />
<DatePicker label='Date' granularity='second' />
<DatePicker label='Date' granularity='minute' />
<DatePicker label='Date' granularity='hour' />
<DatePicker label='Date' granularity='day' />

<DatePicker
  label="Date"
  granularity="millisecond"
/>
<DatePicker
  label="Date"
  granularity="second"
/>
<DatePicker
  label="Date"
  granularity="minute"
/>
<DatePicker
  label="Date"
  granularity="hour"
/>
<DatePicker
  label="Date"
  granularity="day"
/>

Hour Cycle

The hour cycle of the DatePicker can be modified through the hourCycle prop.

<DatePicker label='Date' granularity='minute' hourCycle={12} />
<DatePicker label='Date' granularity='minute' hourCycle={24} />

<DatePicker
  label="Date"
  granularity="minute"
  hourCycle={12}
/>
<DatePicker
  label="Date"
  granularity="minute"
  hourCycle={24}
/>

<DatePicker
  label="Date"
  granularity="minute"
  hourCycle={12}
/>
<DatePicker
  label="Date"
  granularity="minute"
  hourCycle={24}
/>

Timezone

If you add a granulatiry smaller than day it will automatically display a timefield with the timezone. You can hide the timezone through the hideTimeZone prop.

<DatePicker label="Date" granularity="minute" hideTimeZone />

<DatePicker
  label="Date"
  granularity="minute"
  hideTimeZone
/>

<DatePicker
  label="Date"
  granularity="minute"
  hideTimeZone
/>

Visible Months

You can decide how many months should be displayed in the calendar through the maxVisibleMonths prop. If the screen cannot fit the number of months, the calendar will automatically reduce them.

<DatePicker label='Date' maxVisibleMonths={3} />

<DatePicker label='Date' maxVisibleMonths={3} />

<DatePicker
  label="Date"
  maxVisibleMonths={3}
/>

Format Help Text

The date picker can display a format help text through the showFormatHelpText prop.

<DatePicker label='Date' showFormatHelpText />

<DatePicker label='Date' showFormatHelpText />

<DatePicker
  label="Date"
  showFormatHelpText
/>

Labeling

A DatePicker component should be labeled with a visual text through the label prop. If the DatePicker does not include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

<DatePicker label='Date' />

<DatePicker label='Date' />

<DatePicker label="Date" />

Label Alignment

For languages that are read left-to-right (LTR), such as English, the label of the DatePicker component is displayed on the left side of the input. For right-to-left (RTL) languages, such as Arabic, this is flipped. You can control the position of the label through the labelPlacement prop.

<DatePicker label='Date' labelPlacement='top end' />

<DatePicker label='Date' labelPlacement='top end' />

<DatePicker
  label="Date"
  labelPlacement="top end"
/>

Label Position

By default, the label of the DatePicker component is displayed above the input. With the labelPlacement prop this placement can be adjusted to be on the side of the input.

<DatePicker label='Date' labelPlacement='side end' />

<DatePicker label='Date' labelPlacement='side end' />

<DatePicker
  label="Date"
  labelPlacement="side end"
/>

Required

To indicate to the user that the DatePicker is required you can use the isRequired prop.

<DatePicker label='Date' isRequired />

<DatePicker label='Date' isRequired />

<DatePicker
  label="Date"
  isRequired
/>

Validation

The DatePicker component has built-in accessible validation support. To indicate whether the field is valid or not you can use the errorMessage prop.

function Example() {
  const [value, setValue] = useState();

  const isValid = !!value;

  return (
    <DatePicker 
      label='Date' 
      value={value}
      onChange={setValue} 
      errorMessage={!isValid && 'Selecting a date is required.'} 
    />
  );
}

function Example() {
  const [value, setValue] = useState();

  const isValid = !!value;

  return (
    <DatePicker
      label="Date"
      value={value}
      onChange={setValue}
      errorMessage={!isValid &&
        'Selecting a date is required.'}
    />
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState();

  const isValid =
    !!value;

  return (
    <DatePicker
      label="Date"
      value={value}
      onChange={setValue}
      errorMessage={!isValid &&
        'Selecting a date is required.'}
    />
  );
}

Description

To give further instructions or more verbose examples to the user about a DatePicker you can provide a description prop. Avoid using error like tone of voice of the message. If an errorMessage prop is provided it will replace the description.

<DatePicker label="Date" description="Please select a date" />

<DatePicker
  label="Date"
  description="Please select a date"
/>

<DatePicker
  label="Date"
  description="Please select a date"
/>

Placeholder

To give further instructions or examples to the user about a DatePicker you can provide a placeholderValue prop.

<DatePicker label="Date" placeholderValue={new CalendarDate(1980, 1, 1)} />

<DatePicker
  label="Date"
  placeholderValue={new CalendarDate(1980, 1, 1)}
/>

<DatePicker
  label="Date"
  placeholderValue={new CalendarDate(
    1980,
    1,
    1
  )}
/>

Contextual Help

To offer the user contextual help, the DatePicker supports passing a contextualHelp prop, that accepts a ReactNode.

<DatePicker 
  label='Time' 
  contextualHelp={(
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        </Text>
      </Content>
    </ContextualHelp>
  )} 
/>

<DatePicker
  label="Time"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur
          adipiscing elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

<DatePicker
  label="Time"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>
          Lorem Ipsum
        </Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum
          dolor sit
          amet,
          consectetur
          adipiscing
          elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

Disabled

The DatePicker component can be disabled via the isDisabled prop.

<DatePicker
  label="Date"
  defaultValue={new CalendarDate(2019, 2, 3)}
  isDisabled
/>

<DatePicker
  label="Date"
  defaultValue={new CalendarDate(2019, 2, 3)}
  isDisabled
/>

<DatePicker
  label="Date"
  defaultValue={new CalendarDate(
    2019,
    2,
    3
  )}
  isDisabled
/>

Read Only

The DatePicker component can be marked as read only via the isReadOnly prop.

<DatePicker
  label="Date"
  defaultValue={new CalendarDate(2019, 2, 3)}
  isReadOnly
/>

<DatePicker
  label="Date"
  defaultValue={new CalendarDate(2019, 2, 3)}
  isReadOnly
/>

<DatePicker
  label="Date"
  defaultValue={new CalendarDate(
    2019,
    2,
    3
  )}
  isReadOnly
/>

Accessibility

In order to support internationalization, provide a localized string to the label or aria-label prop.

API