Date Picker
Date Pickers allow users to select a Date and Time from a pop up Calendar.
Example
from deephaven import ui
dp = ui.date_picker(
label="Date Picker",
default_value="2024-01-02T10:30:00 UTC",
on_change=print,
)
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:
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.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.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:
- If the input is one of the three Java date types, use that type.
- A date string such as “2007-12-03” will parse to a
LocalDate
- A string with a date, time, and timezone such as “2021-04-12T14:13:07 America/New_York” will parse to a
ZonedDateTime
- 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:
value
default_value
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.
from deephaven import ui
from deephaven.time import to_j_local_date, dh_today, to_j_instant, to_j_zdt
zoned_date_time = to_j_zdt("1995-03-22T11:11:11.23142 America/New_York")
instant = to_j_instant("2022-01-01T00:00:00 ET")
local_date = to_j_local_date(dh_today())
@ui.component
def date_picker_test(value):
date, set_date = ui.use_state(value)
return [ui.date_picker(on_change=set_date, value=date), ui.text(str(date))]
zoned_date_picker = date_picker_test(zoned_date_time)
instant_date_picker = date_picker_test(instant)
local_date_picker = date_picker_test(local_date)
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.
from deephaven.time import dh_now
from deephaven import ui
dp = ui.date_picker(
label="Date Picker",
default_value=dh_now(),
on_change=print,
)
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.
from deephaven import ui
dp1 = ui.date_picker(
label="Date Picker",
placeholder_value="2022-10-01T08:30:00 ET",
on_change=print,
)
dp2 = ui.date_picker(
label="Date Picker",
on_change=print,
)
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.
from deephaven import ui
@ui.component
def date_picker_variants():
return [
ui.date_picker(description="description"),
ui.date_picker(error_message="error", validation_state="valid"),
ui.date_picker(error_message="error", validation_state="invalid"),
ui.date_picker(min_value="2024-01-01", max_value="2024-01-05"),
ui.date_picker(value="2024-07-27T16:10:10 America/New_York", hour_cycle=24),
ui.date_picker(granularity="YEAR"),
ui.date_picker(granularity="MONTH"),
ui.date_picker(granularity="DAY"),
ui.date_picker(granularity="HOUR"),
ui.date_picker(granularity="MINUTE"),
ui.date_picker(granularity="SECOND"),
]
date_picker_variants_example = date_picker_variants()
Time table filtering
Date Pickers can be used to filter tables with time columns.
from deephaven.time import dh_now
from deephaven import time_table, ui
@ui.component
def date_table_filter(table, start_date, end_date, time_col="Timestamp"):
after_date, set_after_date = ui.use_state(start_date)
before_date, set_before_date = ui.use_state(end_date)
return [
ui.date_picker(label="Start Date", value=after_date, on_change=set_after_date),
ui.date_picker(label="End Date", value=before_date, on_change=set_before_date),
table.where(f"{time_col} >= after_date && {time_col} < before_date"),
]
SECONDS_IN_DAY = 86400
today = dh_now()
_table = time_table("PT1s").update_view(
["Timestamp=today.plusSeconds(SECONDS_IN_DAY*i)", "Row=i"]
)
date_filter = date_table_filter(_table, today, today.plusSeconds(SECONDS_IN_DAY * 10))
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. |