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.
Props
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.
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 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} /> </Box> </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" 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).
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> ); }
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> ); }
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> ); }
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
DateField consumes external handlers from GlobalEventsHandlerProvider.
Handlers:
- onRender: executed when DateField mounts for the first time
See GlobalEventsHandlerProvider for more information.
Internal documentation
Related
DatePicker
Use DatePicker if the user is allowed to pick a date from a calendar popup.