DateField
Experimental

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.

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

Figma:

N/A

Responsive:

N/A

Adaptive:

N/A

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	`(arg1: { value: Date \| null }) => 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 \| null`	-
	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 `onError`with 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`	`Locale`	-
	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`	`(arg1: { event: React.FocusEvent<HTMLInputElement>; value: string }) => void`	-
	Callback triggered when the user blurs the input.
`onError`	`(arg1: { errorMessage: string; value: Date \| null }) => void`	-
	Callback triggered when the value entered is invalid. See the controlled component example to learn more.
`onFocus`	`(arg1: { event: React.FocusEvent<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.
`size`	`"md" \| "lg"`	`"lg"`
	Defines the height of ComboBox: md: 40px, lg: 48px. Width is defined by parent component.

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

Date format locales

DateField supports multiple locales. Adjust the date format to each date-fns locale.

The following locale examples show the different locale format variants.

Note that locale data from date-fns is external to gestalt-datepicker, it's not an internal dependency. Add date-fns to your app's dependencies.

import { DateField } from 'gestalt-datepicker';
import { it } from 'date-fns/locale';
<DateField localeData={it}/>

Use the SelectList to try out different locales by passing in the localeData prop.

Country

English (US)

Variants

Controlled component

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

import { useState } from 'react';
import { 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"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <DateField
        errorMessage={errorText || undefined}
        helperText="Enter your date of birth"
        id="mainExample"
        label="Date of birth"
        name="bday_datefield"
        onChange={({ value }) => {
          setDateValue(value);
        }}
        onClearInput={() => setDateValue(null)}
        onError={({ errorMessage }) => setErrorText(errorMessage)}
        value={dateValue}
      />
    </Flex>
  );
}

Size

DateField is available in 'md' and 'lg' size.

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

export default function TextFieldSizes() {
  const [input1Text, setInput1Text] = useState(null);
  const [input2Text, setInput2Text] = useState(null);

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={6} width="100%">
        <DateField
          id="size-datefield-md-no-label"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput1Text(value);
          }}
          onClearInput={() => setInput1Text(null)}
          size="md"
          value={input1Text}
        />
        <DateField
          id="size-datefield-lg-no-label"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput2Text(value);
          }}
          onClearInput={() => setInput2Text(null)}
          size="lg"
          value={input2Text}
        />
        <DateField
          id="size-datefield-md"
          label="Date of birth"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput1Text(value);
          }}
          onClearInput={() => setInput1Text(null)}
          size="md"
          value={input1Text}
        />
        <DateField
          id="size-datefield-lg"
          label="Date of birth"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput2Text(value);
          }}
          onClearInput={() => setInput2Text(null)}
          size="lg"
          value={input2Text}
        />
      </Flex>
    </Box>
  );
}

State

Enabled
The enabled state of DateField that represents it can be interacted with.
Error
DateField can display an error message. DateField can communicate input errors to the user. Use onError and errorMessage to implement it correctly. Check the Disable past & future dates variant for guidance on implementation.
Read-only
Read-only DateField are used to present information to the user without allowing them to edit the content. Typically they are used to show content or information that the user does not have permission or access to edit.
Disabled
DateField cannot be interacted with using the mouse or keyboard. They also do not need to meet contrast requirements, so do not use them to present info to the user (use "readOnly" instead).

Enabled

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

export default function TextFieldSizes() {
  const [input1Text, setInput1Text] = useState(null);
  const [input2Text, setInput2Text] = useState(null);

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={6} width="100%">
        <DateField
          id="enabled-datefield-md"
          label="Date of birth"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput1Text(value);
          }}
          onClearInput={() => setInput1Text(null)}
          size="md"
          value={input1Text}
        />
        <DateField
          id="enabled-datefield-lg"
          label="Date of birth"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput2Text(value);
          }}
          onClearInput={() => setInput2Text(null)}
          size="lg"
          value={input2Text}
        />
      </Flex>
    </Box>
  );
}

Disabled

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

export default function TextFieldSizes() {
  const [input1Text, setInput1Text] = useState(new Date('1995-12-17T03:24:00'));
  const [input2Text, setInput2Text] = useState(new Date('1995-12-17T03:24:00'));

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={6} width="100%">
        <DateField
          disabled
          id="disabled-datefield-md"
          label="Date of birth"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput1Text(value);
          }}
          onClearInput={() => setInput1Text(null)}
          size="md"
          value={input1Text}
        />
        <DateField
          disabled
          id="disabled-datefield-lg"
          label="Date of birth"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput2Text(value);
          }}
          onClearInput={() => setInput2Text(null)}
          size="lg"
          value={input2Text}
        />
      </Flex>
    </Box>
  );
}

Error

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

export default function Example() {
  const [dateValue1] = useState(null);
  const [dateValue2] = useState(null);

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={6} width="100%">
        <DateField
          disableRange="disableFuture"
          errorMessage="Please, select a valid birth date"
          helperText="Enter your date of birth"
          id="error-datefield-md"
          label="Date of birth"
          name="bday_datefield"
          onChange={() => {}}
          onClearInput={() => {}}
          onError={() => {}}
          size="md"
          value={dateValue1}
        />
        <DateField
          disableRange="disableFuture"
          errorMessage="Please, select a valid birth date"
          helperText="Enter your date of birth"
          id="error-datefield-lg"
          label="Date of birth"
          name="bday_datefield"
          onChange={() => {}}
          onClearInput={() => {}}
          onError={() => {}}
          size="lg"
          value={dateValue2}
        />
      </Flex>
    </Box>
  );
}

Read-only

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

export default function TextFieldSizes() {
  const [input1Text, setInput1Text] = useState(new Date('1995-12-17T03:24:00'));
  const [input2Text, setInput2Text] = useState(new Date('1995-12-17T03:24:00'));

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={6} width="100%">
        <DateField
          id="readonly-datefield-md"
          label="Date of birth"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput1Text(value);
          }}
          onClearInput={() => setInput1Text(null)}
          readOnly
          size="md"
          value={input1Text}
        />
        <DateField
          id="readonly-datefield-lg"
          label="Date of birth"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput2Text(value);
          }}
          onClearInput={() => setInput2Text(null)}
          readOnly
          size="lg"
          value={input2Text}
        />
      </Flex>
    </Box>
  );
}

Label

'label' is an optional prop; however, DateField should always be properly labelled.
Check TextField's Label variant section for more examples and guidance.

Helper text

Whenever you want to provide more information about a form field, you should use helperText.

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

export default function TextFieldSizes() {
  const [input1Text, setInput1Text] = useState(null);
  const [input2Text, setInput2Text] = useState(null);

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={6} width="100%">
        <DateField
          helperText="Enter your date of birth"
          id="helperText-datefield-md"
          label="Date of birth"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput1Text(value);
          }}
          onClearInput={() => setInput1Text(null)}
          size="md"
          value={input1Text}
        />
        <DateField
          helperText="Enter your date of birth"
          id="helperText-datefield-lg"
          label="Date of birth"
          name="bday_datefield"
          onChange={({ value }) => {
            setInput2Text(value);
          }}
          onClearInput={() => setInput2Text(null)}
          size="lg"
          value={input2Text}
        />
      </Flex>
    </Box>
  );
}

Disable past & future dates

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

External handlers

Experimental

DateField consumes external handlers from GlobalEventsHandlerProvider.

Handlers:

onRender: executed when DateField mounts for the first time

See GlobalEventsHandlerProvider for more information.

Internal documentation

PDocs available

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

Edit page on GitHub

DateField Experimental