Date Picker

Date Pickers allow users to select a Date and Time from a pop up Calendar.

Example

Date types

The date picker accepts the following date types as inputs:
\\ None, LocalDate, ZoneDateTime, Instant, int, str, datetime.datetime, numpy.datetime64, pandas.Timestamp

The input will be converted to one of three Java date types:

1. LocalDate: A LocalDate is a date without a time zone in the ISO-8601 system, such as “2007-12-03” or “2057-01-28”. This will create a date picker with a granularity of days.
2. Instant: An Instant represents an unambiguous specific point on the timeline, such as 2021-04-12T14:13:07 UTC. This will create a date picker with a granularity of seconds in UTC. The time zone will be rendered as the time zone in user settings.
3. ZonedDateTime: A ZonedDateTime represents an unambiguous specific point on the timeline with an associated time zone, such as 2021-04-12T14:13:07 America/New_York. This will create a date picker with a granularity of seconds in the specified time zone. The time zone will be rendered as the specified time zone.

The input is coverted according to the following rules:

1. If the input is one of the three Java date types, use that type.
2. A date string such as “2007-12-03” will parse to a LocalDate
3. A string with a date, time, and timezone such as “2021-04-12T14:13:07 America/New_York” will parse to a ZonedDateTime
4. All other types will attempt to convert in this order: Instant, ZonedDateTime, LocalDate

The format of the date picker and the type of the value passed to the on_change handler is determined by the type of the following props in order of precedence:

1. value
2. default_value
3. placeholder_value

If none of these are provided, the on_change handler will be passed an Instant.

Controlled mode with value

Setting the value prop will put the date_picker in controlled mode. Selecting a new date will call the on_change callback. Then value must be updated programatically to render the new value. This can be done using the use_state hook.

Uncontrolled mode with default_value

If the value prop is omitted, the date_picker will be in uncontrolled mode. It will store its state internally and automatically update when a new date is selected. In this mode, setting the default_value prop will determine the initial value displayed by the date_picker.

Uncontrolled mode with placeholder_value

If both value and default_value are omitted, the date_picker will be in uncontrolled mode displaying no date selected. When opened, the date picker will suggest the date from the placeholder_value prop. Omitting placeholder_value will default it to today at the current time on the server machine time zone.

Events

Date Pickers accept a value to display and can trigger actions based on events such as setting state when changed. See the API Reference for a full list of available events.

Variants

Date Pickers can have different variants to indicate their purpose.

Time table filtering

Date Pickers can be used to filter tables with time columns.

API Reference

A date picker allows the user to select a date.

Returns: Element The date picker element.

Parameters	Type	Default	Description
placeholder_value	DType | None | str | date | datetime | datetime64 | Timestamp | int	None	A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today at midnight in the user's timezone.
value	DType | None | str | date | datetime | datetime64 | Timestamp | int | UndefinedType	<deephaven.ui.types.types.UndefinedType object>	The current value (controlled).
default_value	DType | None | str | date | datetime | datetime64 | Timestamp | int | UndefinedType	<deephaven.ui.types.types.UndefinedType object>	The default value (uncontrolled).
min_value	DType | None | str | date | datetime | datetime64 | Timestamp | int	None	The minimum allowed date that a user may select.
max_value	DType | None | str | date | datetime | datetime64 | Timestamp | int	None	The maximum allowed date that a user may select.
granularity	Literal['DAY', 'HOUR', 'MINUTE', 'SECOND'] | None	None	Determines the smallest unit that is displayed in the date picker. By default, this is "DAY" for LocalDate, and "SECOND" otherwise.
page_behavior	Literal['single', 'visible'] | None	None	Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
hour_cycle	Literal[12, 24] | None	None	Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
hide_time_zone	bool	False	Whether to hide the time zone abbreviation.
should_force_leading_zeros	bool | None	None	Whether to always show leading zeros in the month, day, and hour fields. By default, this is determined by the user's locale.
is_disabled	bool | None	None	Whether the input is disabled.
is_read_only	bool | None	None	Whether the input can be selected but not changed by the user.
is_required	bool | None	None	Whether user input is required on the input before form submission.
validation_behavior	Literal['aria', 'native'] | None	None	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
auto_focus	bool | None	None	Whether the element should receive focus on render.
label	None | bool | int | str | Element | List[NodeType]	None	The content to display as the label.
description	Element | None	None	A description for the field. Provides a hint such as specific requirements for what to choose.
error_message	Element | None	None	An error message for the field.
is_open	bool | None	None	Whether the overlay is open by default (controlled).
default_open	bool | None	None	Whether the overlay is open by default (uncontrolled).
name	str | None	None	The name of the input element, used when submitting an HTML form.
max_visible_months	int | None	None	The maximum number of months to display at once in the calendar popover, if screen space permits.
should_flip	bool | None	None	Whether the calendar popover should automatically flip direction when space is limited.
is_quiet	bool | None	None	Whether the date picker should be displayed with a quiet style.
show_format_help_text	bool | None	None	Whether to show the localized date format as help text below the field.
label_position	Literal['top', 'side'] | None	None	The label's overall position relative to the element it is labeling.
label_align	Literal['start', 'end'] | None	None	The label's horizontal alignment relative to the element it is labeling.
necessity_indicator	Literal['icon', 'label'] | None	None	Whether the required state should be shown as an icon or text.
contextual_help	Element | None	None	A ContextualHelp element to place next to the label.
validation_state	Literal['valid', 'invalid'] | None	None	Whether the input should display its "valid" or "invalid" visual styling.
key	str | None	None	A unique identifier used by React to render elements in a list.