DateField is used when the user has to select a date. Compared to DatePicker, DateField has no supporting calendar to select a date, the user must input date values with a numeric keyboard.

DateField is distributed within the "gestalt-datepicker" package and must be installed separately.

also known as

DateField is an experimental component. Expect development and design iteration, breaking API changes or even component deprecation.
Figma:

Web:

iOS:

Android:

A11y:

Props

Component props
Name
Type
Default
id
Required
string
-

A unique identifier for the input. See the controlled component example to learn more.

onChange
Required
({| value: ?Date |}) => void
-

DateField is a controlled component. onChange is the callback triggered when the value of the input changes. Should be used to modify the controlled value. See the controlled component example to learn more.

onClearInput
Required
() => void
-

DateField is a controlled component. onClearInput is the callback triggered when the user clicks on the "clear" icon button. Should be used to clear the entered dates in the controlled component. See the controlled component example to learn more.

value
Required
?Date
-

DateField is a controlled component. value sets the current value of the input. See the controlled component example to learn more.

autoComplete
"bday" | "off"
-

Indicate if birthday autocomplete should be available on the input.

disabled
boolean
false

Indicate if the input is disabled. See the disabled example for more details.

disableRange
"disableFuture" | "disablePast"
-

Prevent the user from selecting future or past dates. "disableFuture" disables values after the current date and "disablePast" disables values before the current date. This will return an error on onErrorwith values "disableFuture" or "disablePast". See the controlled component example to learn more.

errorMessage
string
-

Customize your error message for the cases the user enters invalid dates. See the controlled component example to learn more.

helperText
string
-

More information about how to complete the date field. See the controlled component example to learn more.

label
string
-

The label for the input. Be sure to localize the text. See the controlled component example to learn more.

labelDisplay
"visible" | "hidden"
"visible"

Whether the label should be visible or not. If hidden, the label is still available for screen reader users, but does not appear visually.

localeData
{|
  code?: string,
  formatDistance?: (...args: $ReadOnlyArray<{ ... }>) => { ... },
  formatRelative?: (...args: $ReadOnlyArray<{ ... }>) => { ... },
  localize?: {|
    ordinalNumber: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    era: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    quarter: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    month: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    day: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    dayPeriod: (...args: $ReadOnlyArray<{ ... }>) => { ... },
  |},
  formatLong?: {|
    date: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    time: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    dateTime: (...args: $ReadOnlyArray<{ ... }>) => { ... },
  |},
  match?: {|
    ordinalNumber: (...args: $ReadOnlyArray<string>) => { ... },
    era: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    quarter: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    month: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    day: (...args: $ReadOnlyArray<{ ... }>) => { ... },
    dayPeriod: (...args: $ReadOnlyArray<{ ... }>) => { ... },
  |},
  options?: {|
    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
    firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7,
  |},
|}
-

DatePicker accepts imported locales from the open source date utility library date-fns. See the locales example to learn more.

maxDate
Date
-

Maximal selectable date. Disables any date values after the provided date.

minDate
Date
-

Minimal selectable date. Disables any date values before the provided date.

mobileEnterKeyHint
"enter" | "done" | "go" | "next" | "previous" | "search" | "send"
-

Mobile only prop. Optionally specify the action label to present for the enter key on virtual keyboards.

name
string
-

A unique name for the input. See the controlled component example to learn more.

onBlur
({|
  event: SyntheticFocusEvent<HTMLInputElement>,
  value: string,
|}) => void
-

Callback triggered when the user blurs the input.

onError
({|
  errorMessage: string,
  value: ?Date,
|}) => void
-

Callback triggered when the value entered is invalid. See the controlled component example to learn more.

onFocus
({|
  event: SyntheticFocusEvent<HTMLInputElement>,
  value: string,
|}) => void
-

Callback triggered when the user focuses the input.

readOnly
boolean
false

Indicate if the input is readOnly. See the readOnly example for more details.

Variants

Controlled component

DateField is a controlled component. Use value, onChange, onClearInput and onError to implement it correctly.

import { useState } from 'react';
import { Box, Flex } from 'gestalt';
import { DateField } from 'gestalt-datepicker';

export default function Example() {
  const [dateValue, setDateValue] = useState(null);
  const [errorText, setErrorText] = useState(null);

  return (
    <Flex
      alignItems="center"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Box width={400}>
        <DateField
          id="mainExample"
          label="Date of birth"
          helperText="Enter your date of birth"
          onError={({ errorMessage }) => setErrorText(errorMessage)}
          errorMessage={errorText || undefined}
          onChange={({ value }) => {
            setDateValue(value);
          }}
          value={dateValue}
          onClearInput={() => setDateValue(null)}
          name="bday_datefield"
        />
      </Box>
    </Flex>
  );
}

Error messaging

DateField can communicate input errors to the user. Use onError and errorMessage to implement it correctly.

import { useState } from 'react';
import { Box, Flex } from 'gestalt';
import { DateField } from 'gestalt-datepicker';

export default function Example() {
  const [dateValue, setDateValue] = useState(null);
  const [errorText, setErrorText] = useState(null);

  return (
    <Flex
      alignItems="center"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Box width={400}>
        <DateField
          id="errorExample"
          label="Date of birth"
          helperText="Enter your date of birth"
          onError={({ errorMessage, value }) => {
            const date = value ? new Date(value) : null;

            if (errorMessage === 'invalidDate') return;
            if (
              errorMessage === 'disableFuture' ||
              (date && date.getFullYear() === 1)
            )
              setErrorText('Please, select a valid birth date');
            if (date && date.getFullYear() > 1) setErrorText(null);
          }}
          errorMessage={errorText || undefined}
          onChange={({ value }) => {
            setDateValue(value);
          }}
          value={dateValue}
          disableRange="disableFuture"
          onClearInput={() => {
            setErrorText(null);
            setDateValue(null);
          }}
          name="bday_datefield"
        />
      </Box>
    </Flex>
  );
}

States

DateField supports disabled and readOnly states.

import { Box, Flex } from 'gestalt';
import { DateField } from 'gestalt-datepicker';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
      direction="column"
    >
      <Box width={400}>
        <DateField
          id="disabled_example"
          disabled
          label="Date of birth"
          onError={() => {}}
          onChange={() => {}}
          value={new Date('1995-12-17T03:24:00')}
          onClearInput={() => {}}
          name="bday_datefield"
        />
      </Box>
      <Box width={400}>
        <DateField
          id="readonly_example"
          readOnly
          label="Date of birth"
          onError={() => {}}
          onChange={() => {}}
          value={new Date('1995-12-17T03:24:00')}
          onClearInput={() => {}}
          name="bday_datefield"
        />
      </Box>
    </Flex>
  );
}

Disable future & past

DateField supports disabling future & past dates from being selected.

import { useState } from 'react';
import { Box, Flex } from 'gestalt';
import { DateField } from 'gestalt-datepicker';

export default function Example() {
  const [dateValueDisableFuture, setDateValueDisableFuture] = useState(null);
  const [dateValueDisablePast, setDatealueDisablePast] = useState(null);

  const [errorTextDisableFuture, setErrorTextDisableFuture] = useState(null);
  const [errorTextDisablePast, setErrorTextDisablePast] = useState(null);

  return (
    <Flex
      alignItems="center"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
      direction="column"
    >
      <Box width={400}>
        <DateField
          id="disableFuture"
          label="Date of birth"
          helperText="Enter your date of birth"
          onError={({ errorMessage }) =>
            setErrorTextDisableFuture(errorMessage)
          }
          errorMessage={
            (errorTextDisableFuture &&
              errorTextDisableFuture === 'disableFuture' &&
              'Please, enter a valid past date') ||
            undefined
          }
          onChange={({ value }) => {
            setDateValueDisableFuture(value);
          }}
          value={dateValueDisableFuture}
          onClearInput={() => setDateValueDisableFuture(null)}
          name="bday_datefield"
          disableRange="disableFuture"
        />
      </Box>
      <Box width={400}>
        <DateField
          id="disablePast"
          label="Campaign activation date"
          helperText="Enter an activation date for your campaign"
          onError={({ errorMessage }) => setErrorTextDisablePast(errorMessage)}
          errorMessage={
            (errorTextDisablePast &&
              errorTextDisablePast === 'disablePast' &&
              'Please, enter a valid future date') ||
            undefined
          }
          onChange={({ value }) => {
            setDatealueDisablePast(value);
          }}
          value={dateValueDisablePast}
          onClearInput={() => setDatealueDisablePast(null)}
          name="bday_datefield"
          disableRange="disablePast"
        />
      </Box>
    </Flex>
  );
}

Supporting locales

localeDataCode="af"
localeDataCode="ar-SA"
localeDataCode="bg"
localeDataCode="cs-CZ"
localeDataCode="da-DK"
localeDataCode="de"
localeDataCode="el-GR"
localeDataCode="en-GB"
localeDataCode="en-US"
localeDataCode="es"
localeDataCode="fi-FI"
localeDataCode="fr"
localeDataCode="he"
localeDataCode="hi-IN"
localeDataCode="hr"
localeDataCode="hu-HU"
localeDataCode="id-ID"
localeDataCode="it"
localeDataCode="ja"
localeDataCode="ko-KR"
localeDataCode="ms-MY"
localeDataCode="nb-NO"
localeDataCode="nl"
localeDataCode="pl-PL"
localeDataCode="pt-BR"
localeDataCode="pt-PT"
localeDataCode="ro-RO"
localeDataCode="ru-RU"
localeDataCode="sk-SK"
localeDataCode="sv-SE"
localeDataCode="th-TH"
localeDataCode="tr"
localeDataCode="uk-UA"
localeDataCode="vi-VN"
localeDataCode="zh-CN"
localeDataCode="zh-TW"
  **[DatePicker](/DatePicker)**

Use DatePicker if the user is allowed to pick a date from a calendar popup.