DateRangePicker

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

Uncontrolled Value

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

<DateRangePicker
  label="Date"
  defaultValue={{
    start: new CalendarDate(2019, 2, 3),
    end: new CalendarDate(2019, 2, 10)
  }}
/>

<DateRangePicker
  label="Date"
  defaultValue={{
    start: new CalendarDate(2019, 2, 3),
    end: new CalendarDate(2019, 2, 10)
  }}
/>

<DateRangePicker
  label="Date"
  defaultValue={{
    start:
      new CalendarDate(
        2019,
        2,
        3
      ),
    end:
      new CalendarDate(
        2019,
        2,
        10
      )
  }}
/>

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({
    start: new CalendarDate(2019, 2, 3),
    end: new CalendarDate(2019, 2, 10)
  });

  return (
    <DateRangePicker
      label="Date"
      value={value}
      onChange={setValue}
    />
  );
}

function Example() {
  const [value, setValue] = useState({
    start: new CalendarDate(2019, 2, 3),
    end: new CalendarDate(2019, 2, 10)
  });

  return (
    <DateRangePicker
      label="Date"
      value={value}
      onChange={setValue}
    />
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState({
    start:
      new CalendarDate(
        2019,
        2,
        3
      ),
    end:
      new CalendarDate(
        2019,
        2,
        10
      )
  });

  return (
    <DateRangePicker
      label="Date"
      value={value}
      onChange={setValue}
    />
  );
}

Granularity

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

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

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

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

Hour Cycle

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

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

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

<DateRangePicker
  label="Date"
  granularity="minute"
  hourCycle={12}
/>
<DateRangePicker
  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.

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

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

<DateRangePicker
  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.

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

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

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

Format Help Text

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

<DateRangePicker label='Date' showFormatHelpText />

<DateRangePicker label='Date' showFormatHelpText />

<DateRangePicker
  label="Date"
  showFormatHelpText
/>

Labeling

A DateRangePicker component should be labeled with a visual text through the label prop. If the DateRangePicker 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.

<DateRangePicker label='Date' />

<DateRangePicker label='Date' />

<DateRangePicker label="Date" />

Label Alignment

For languages that are read left-to-right (LTR), such as English, the label of the DateRangePicker 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.

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

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

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

Label Position

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

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

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

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

Required

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

<DateRangePicker label='Date' isRequired />

<DateRangePicker label='Date' isRequired />

<DateRangePicker
  label="Date"
  isRequired
/>

Validation

The DateRangePicker 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 (
    <DateRangePicker 
      label='Date' 
      value={value}
      onChange={setValue} 
      errorMessage={!isValid && 'Selecting a date is required.'} 
    />
  );
}

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

  const isValid = !!value;

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

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

  const isValid =
    !!value;

  return (
    <DateRangePicker
      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 DateRangePicker 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.

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

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

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

Placeholder

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

<DateRangePicker
  label="Date"
  placeholderValue={new CalendarDate(2019, 2, 3)}
/>

<DateRangePicker
  label="Date"
  placeholderValue={new CalendarDate(2019, 2, 3)}
/>

<DateRangePicker
  label="Date"
  placeholderValue={new CalendarDate(
    2019,
    2,
    3
  )}
/>

Contextual Help

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

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

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

<DateRangePicker
  label="Date"
  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 DateRangePicker component can be disabled via the isDisabled prop.

<DateRangePicker
  label="Date"
  defaultValue={{
    start: new CalendarDate(2019, 2, 3),
    end: new CalendarDate(2019, 2, 10)
  }}
  isDisabled
/>

<DateRangePicker
  label="Date"
  defaultValue={{
    start: new CalendarDate(2019, 2, 3),
    end: new CalendarDate(2019, 2, 10)
  }}
  isDisabled
/>

<DateRangePicker
  label="Date"
  defaultValue={{
    start:
      new CalendarDate(
        2019,
        2,
        3
      ),
    end:
      new CalendarDate(
        2019,
        2,
        10
      )
  }}
  isDisabled
/>

Read Only

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

<DateRangePicker
  label="Date"
  defaultValue={{
    start: new CalendarDate(2019, 2, 3),
    end: new CalendarDate(2019, 2, 10)
  }}
  isReadOnly
/>

<DateRangePicker
  label="Date"
  defaultValue={{
    start: new CalendarDate(2019, 2, 3),
    end: new CalendarDate(2019, 2, 10)
  }}
  isReadOnly
/>

<DateRangePicker
  label="Date"
  defaultValue={{
    start:
      new CalendarDate(
        2019,
        2,
        3
      ),
    end:
      new CalendarDate(
        2019,
        2,
        10
      )
  }}
  isReadOnly
/>

Accessibility

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

API