DateField

A date field allows the user to enter a date to an input.

Uncontrolled Value

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

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

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

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

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>
      <DateField 
        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>
      <DateField
        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>
      <DateField
        label="Date"
        value={value}
        onChange={setValue}
      />

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

Granularity

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

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

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

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

Hour Cycle

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

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

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

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

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

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

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

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

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

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

Format Help Text

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

<DateField label='Date' showFormatHelpText />

<DateField label='Date' showFormatHelpText />

<DateField
  label="Date"
  showFormatHelpText
/>

Labeling

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

<DateField label='Date' />

<DateField label='Date' />

<DateField label="Date" />

Label Alignment

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

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

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

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

Label Position

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

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

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

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

Required

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

<DateField label='Date' isRequired />

<DateField label='Date' isRequired />

<DateField
  label="Date"
  isRequired
/>

Validation

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

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

  const isValid = !!value;

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

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

  const isValid =
    !!value;

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

Description

To give further instructions or more verbose examples to the user about a DateField 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.

<DateField label="Date" description="Please enter a date" />

<DateField label="Date" description="Please enter a date" />

<DateField
  label="Date"
  description="Please enter a date"
/>

Placeholder

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

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

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

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

Contextual Help

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

<DateField 
  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>
  )} 
/>

<DateField
  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>
  }
/>

<DateField
  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 DateField component can be disabled via the isDisabled prop.

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

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

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

Read Only

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

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

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

<DateField
  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