date-picker

Date Picker

View on MongoDB.design

Installation

Yarn

yarn add @leafygreen-ui/date-picker

NPM

npm install @leafygreen-ui/date-picker

Example

import { DatePicker } from '@leafygreen-ui/date-picker';

const [date, setDate] = useState<Date>();

<DatePicker
  label="Pick a date"
  value={date}
  max={new Date("2026-12-26")}
  onDateChange={setDate}
  locale="iso8601"
  timeZone="utc"
/>;

Properties

Prop	Type	Description	Default
label	ReactNode	Label shown above the date picker.
description	ReactNode	A description for the date picker. It's recommended to set a meaningful time zone representation as the description. (e.g. "Coordinated Universal Time")
locale	'iso8601'| 'string'	Sets the presentation format for the displayed date, and localizes month & weekday labels. Defaults to the user’s browser preference (if available), otherwise ISO-8601.	iso8601
timeZone	string	A valid IANA timezone string, or UTC offset, used to calculate initial values. Defaults to the user’s browser settings.
min	Date	The earliest date accepted, in UTC
max	Date	The latest date accepted, in UTC
value	'Date' | 'InvalidDate' | 'null'	The selected date. Note that this Date object will be read as UTC time. Providing Date.now() could result in the incorrect date being displayed, depending on the system time zone. To set value to today, regardless of timeZone, use setToUTCMidnight(new Date(Date.now())). e.g. 2023-12-31 at 20:00 in Los Angeles, will be 2024-01-01 at 04:00 in UTC. To set the correct day (2023-12-31) as the DatePicker value we must first convert our local timestamp to 2023-12-31 at midnight
onDateChange	(value?: Date | InvalidDate | null) => void	Callback fired when the user makes a value change. Fired on click of a new date in the menu, or on keydown if the input contains a valid date. Not fired when a date segment changes, but does not create a full date Callback date argument will be a Date object in UTC time, or null
initialValue	'Date' | 'InvalidDate' | 'null'	The initial selected date. Ignored if value is provided Note that this Date object will be read as UTC time. See value prop documentation for more details
handleValidation	(value?: Date | InvalidDate | null) => void	A callback fired when validation should run, based on form validation guidelines. Use this callback to compute the correct state and errorMessage value. Callback date argument will be a Date object in UTC time, or null
onChange	(event: ChangeEvent<HTMLInputElement>) => void	Callback fired when any segment changes, (but not necessarily a full value)
baseFontSize	'13' | '16'	The base font size of the input. Inherits from the nearest LeafyGreenProvider
disabled	boolean	Whether the input is disabled. Note: will not set the disabled attribute on an input and the calendar menu will not open if disabled is set to true.	false
size	'small' | 'xsmall' | 'default' | 'large'	Whether the input is disabled. Note: will not set the disabled attribute on an input and the calendar menu will not open if disabled is set to true.	default
state	'none' | 'error'	Whether to show an error message	none
errorMessage	string	A message to show in red underneath the input when state is Error
initialOpen	boolean	Whether the calendar menu is initially open. Note: The calendar menu will not open if disabled is set to true.	false
autoComplete	'off' | 'on' | 'bday'	Whether the input should autofill	off
darkMode	boolean	Render the component in dark mode.	false

Popover Props

Date Picker extends Popover props but omits the following props: active, children, className, dismissMode, onClick, onToggle, popoverZIndex, portalClassName, portalContainer, portalRef, refEl, renderMode, and scrollContainer.

🔎 Glossary

Date format

The pattern in which a string stores date (& time) information. E.g. “YYYY-DD-MM”, “MM/DD/YYYY”, “YYYY-MM-DDTHH:mm:ss.sssZ”

Wire format (or Data format)

The format of the date string passed into the component. This will typically be ISO-8601, but could be any format accepted by the Date constructor.

Presentation format

The format in which the date is presented to the user. By default, the HTML date input element presents this in the format of the user’s Locale (as defined in browser or OS settings).

Locale

Language, script, & region information. Can also include other data.

Time Zone

A string representing a user’s local time zone (e.g. “America/New_York”) or UTC offset. Valid time zones are defined by IANA, and listed on Wikipedia. A UTC offset can be provided in a DateTime string.

UTC offset

The offset of a time zone vs UTC. E.g. The UTC offset for “America/New_York” is -5:00, (or -4:00 depending on daylight savings).

Wire time zone (or Data time zone)

The time zone information contained in the date string/object passed into the component.

Presentation time zone

The time zone relative to which we present date information to the user. Can result in a different day than the wire time zone. E.g. “2023-08-08T00:00:00Z” (Aug. 8/2023 at midnight UTC) => “2023-08-07T20:00:00-04:00” (Aug. 7 at 8pm EDT)

Special Case

Aria Labels

Either label or aria-labelledby or aria-label must be provided, or there will be a console error. This is to ensure that screenreaders have a description for what the DatePicker does.