Props
Usage guidelines
- Allowing users to choose a date or date range by clicking through the calendar popup or typing in the text field.
- Limiting date options to a specific range of dates.
- When the native date picking experience is preferred (typically mobile and mWeb experiences). In this case, use TextField with type=”date”.
Accessibility
Localization
Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.
Date format locales
DatePicker 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 { DatePicker } from 'gestalt-datepicker';
import { it } from 'date-fns/locale';
<DatePicker localeData={it}/>
Use the SelectList to try out different locales by passing in the localeData
prop.
Variants
Controlled component
DatePicker is a controlled component. Use value
, onChange
, onClearInput
and onError
to implement it correctly.
DatePicker is controlled when value
is not "undefined". When value
is "undefined", it stays uncontrolled.
- Empty input. If DatePicker doesn't present pre-selected date values, initialize
value
with "null" so the component is controlled. - Pre-selected date values. If DatePicker presents pre-selected date values, initialize
value
with the pre-selected date so the component is controlled.
import { useState } from 'react'; import { Box, Flex } from 'gestalt'; import { DatePicker } from 'gestalt-datepicker'; export default function Example() { const [dateValue, setDateValue] = useState(null); return ( <Flex alignItems="start" height="100%" justifyContent="center" width="100%"> <Box padding={2}> <DatePicker id="example-basic" label="Select a date" onChange={({ value }) => setDateValue(value)} value={dateValue} /> </Box> </Flex> ); }
import { useState } from 'react'; import { Box, Flex } from 'gestalt'; import { DatePicker } from 'gestalt-datepicker'; export default function Example() { const [dateValue, setDateValue] = useState(new Date(1985, 6, 4)); return ( <Flex alignItems="start" height="100%" justifyContent="center" width="100%"> <Box padding={2}> <DatePicker id="example-basic" label="Select a date" onChange={({ value }) => { setDateValue(value); }} value={dateValue} /> </Box> </Flex> ); }
States
- Disabled
- Error. Display an error message. Error message overrides the helper text.
import { useState } from 'react'; import { Box, Flex } from 'gestalt'; import { DatePicker } from 'gestalt-datepicker'; export default function Example() { const [dateValue, setDateValue] = useState(new Date(1985, 6, 4)); return ( <Flex alignItems="start" height="100%" justifyContent="center" width="100%"> <Box padding={2}> <DatePicker disabled id="example-disabled" label="User Activation Date" onChange={({ value }) => setDateValue(value)} value={dateValue} /> </Box> </Flex> ); }
import { useState } from 'react'; import { Box, Flex } from 'gestalt'; import { DatePicker } from 'gestalt-datepicker'; export default function Example() { const [dateValue, setDateValue] = useState(null); return ( <Flex alignItems="start" height="100%" justifyContent="center" width="100%"> <Box padding={2}> <DatePicker errorMessage={dateValue ? undefined : "This field can't be blank!"} helperText="Select a preferred day for your training." id="example-errorMessage" label="Schedule your training" onChange={({ value }) => setDateValue(value)} /> </Box> </Flex> ); }
Helper text
import { useState } from 'react'; import { Box, Flex } from 'gestalt'; import { DatePicker } from 'gestalt-datepicker'; export default function Example() { const [dateValue, setDateValue] = useState(null); return ( <Flex alignItems="start" height="100%" justifyContent="center" width="100%"> <Box padding={2}> <DatePicker id="heleprText" label="Customer service appointment" onChange={({ value }) => setDateValue(value)} value={dateValue} helperText="Select from the next available dateValueDisablePast" minDate={new Date()} /> </Box> </Flex> ); }
Date range
import { useRef, useState } from 'react'; import { Box, Flex } from 'gestalt'; import { DatePicker } from 'gestalt-datepicker'; export default function Example() { const [startDate, setStartDate] = useState(null); const [endDate, setEndDate] = useState(null); const endDateInput = useRef(null); const startDateInput = useRef(null); return ( <Flex alignItems="start" height="100%" justifyContent="center" width="100%"> <Box padding={2}> <Flex gap={{ column: 0, row: 2 }}> <DatePicker rangeStartDate={startDate} rangeEndDate={endDate} id="example-start-date" label="Check In" nextRef={endDateInput} onChange={({ value }) => { setStartDate(value); }} rangeSelector="start" value={startDate} ref={startDateInput} /> <DatePicker rangeStartDate={startDate} rangeEndDate={endDate} id="example-end-date" label="Check Out" nextRef={startDateInput} onChange={({ value }) => setEndDate(value)} rangeSelector="end" value={endDate} ref={endDateInput} /> </Flex> </Box> </Flex> ); }
Disabled dates
DatePicker supports disabling future & past dates as well as an array of selected dates.
import { useState } from 'react'; import { Box, Flex } from 'gestalt'; import { DatePicker } from 'gestalt-datepicker'; export default function Example() { const [dateValueDisableFuture, setDateValueDisableFuture] = useState(null); const [dateValueDisablePast, setDatealueDisablePast] = useState(null); return ( <Flex alignItems="start" gap={4} height="100%" justifyContent="center" width="100%" > <Box padding={4}> <DatePicker id="disableFuture" label="Date of birth" helperText="Enter your date of birth" onChange={({ value }) => setDateValueDisableFuture(value)} value={dateValueDisableFuture} maxDate={new Date()} /> </Box> <Box padding={4}> <DatePicker id="disablePast" label="Campaign activation date" helperText="Enter an activation date for your campaign" onChange={({ value }) => setDatealueDisablePast(value)} value={dateValueDisablePast} name="bday_datefield" minDate={new Date()} /> </Box> </Flex> ); }
import { useState } from 'react'; import { Box, Flex } from 'gestalt'; import { DatePicker } from 'gestalt-datepicker'; export default function Example() { const [dateValue, setDateValue] = useState(new Date(2020, 2, 9)); return ( <Flex alignItems="start" height="100%" justifyContent="center" width="100%"> <Box padding={4}> <DatePicker id="disableSelecxted" label="Select Your Appointment" helperText="Enter an activation date for your campaign" onChange={({ value }) => setDateValue(value)} name="bday_datefield" minDate={new Date()} excludeDates={[new Date(2020, 2, 11), new Date(2020, 2, 12)]} value={dateValue} /> </Box> </Flex> ); }
Select list
Provide select lists for quickly selecting year and month
import { useState } from 'react'; import { Box, Flex, SegmentedControl } from 'gestalt'; import { DatePicker } from 'gestalt-datepicker'; export default function Example() { const mapOptions = { 0: ['month'], 1: ['year'], 2: ['year', 'month'] }; const items = ['Month', 'Year', 'Month & Year']; const [itemIndex, setItemIndex] = useState(0); const [dateValue, setDateValue] = useState(new Date(1985, 6, 4)); return ( <Flex alignItems="start" height="100%" justifyContent="center" width="100%"> <Box padding={2}> <Flex direction="column" gap={4} width="100%"> <SegmentedControl items={items} selectedItemIndex={itemIndex} onChange={({ activeIndex }) => setItemIndex(activeIndex)} /> <DatePicker id="selectLists" label="Alberto's birth date" onChange={({ value }) => setDateValue(value)} value={dateValue} selectLists={mapOptions[itemIndex.toString()]} /> </Flex> </Box> </Flex> ); }
Ideal Direction
Define the preferred direction for the DatePicker popover to open. If that placement doesn't fit, the opposite direction will be used.
External handlers
DatePicker consumes external handlers from GlobalEventsHandlerProvider .
Handlers:
- onRender : executed when DateField mounts for the first time
See GlobalEventsHandlerProvider for more information.
Component quality checklist
Quality item | Status | Status description | |
---|---|---|---|
Figma Library | Ready | Component is available in Figma for web and mobile web. | |
Responsive Web | Ready | Component responds to changing viewport sizes in web and mobile web. | |
Issues | This component has known issues. |