`date_range`

A control that can display and specify a range of dates or times.

The user is expected to select the starting and ending dates defining the date range, typically stored as the first and second element of an array of datetime.date or datetime.datetime objects.
Note that the control does not check whether the first day precedes the second one: should the application enforce that, it must be programmed accordingly.

Warning on Windows

When you are using dates earlier than January 1st, 1970 (the UNIX epoch) in a date range control on a Windows system, you may receive a warning in the console where the script was run, indicating a raised exception in datetime.astimezone().
This is a known problem in the Python implementation, referenced in the Python issue tracker, that Taipy has no workaround for.

Properties¶

Name	Type	Default	Description
`dates`^(★)	`list(datetime` dynamic		The dates that this control represents and can modify. It is typically bound to a list of two `datetime` object.
`with_time`	`bool`	False	Whether or not to show the time part of the date.
`format`	`str`		The format to apply to the value. See below.
`editable`	`bool` dynamic	True	Shows the date as a formatted string if not editable.
`label_start`	`str`		The label associated with the first input.
`label_end`	`str`		The label associated with the second input.
`on_change`	`Callback`		The name of a function that is triggered when the value is updated. The parameters of that function are all optional: state (`State`): the state instance. var_name (str): the variable name. value (any): the new value.
`propagate`	`bool`	App config	Allows the control's main value to be automatically propagated. The default value is defined at the application configuration level. If True, any change to the control's value is immediately reflected in the bound application variable.
`active`	`bool` dynamic	True	Indicates if this component is active. An inactive component allows no user interaction.
`id`	`str`		The identifier that will be assigned to the rendered HTML component.
`properties`	`dict[str, any]`		Bound to a dictionary that contains additional properties for this element.
`class_name`	`str` dynamic		The list of CSS class names that will be associated with the generated HTML Element. These class names will be added to the default `taipy-<element_type>`.
`hover_text`	`str` dynamic		The information that is displayed when the user hovers over this element.

^(★)dates is the default property for this visual element.

Details¶

The format property lets you indicate how to display the date objects set to the dates property. Note that the format is used only when editable is set to False (the date range control is read-only).
The date control has the same property. Please look at this control's documentation for more information on this property.

Styling¶

All the date range controls are generated with the "taipy-date_range" CSS class. You can use this class name to select the date range selectors on your page and apply style.

Usage¶

Selecting a date range¶

The dates property (which is the default property for this control) must be set to an array of two datetime.date objects, representing the selected start and end dates of the range.

Assuming the variable dates was defined by the following code:

import datetime

start_date = datetime.date(1756, 1, 27)
end_date   = datetime.date(1791, 12, 5)
dates = [start_date, end_date]

The definition of the date range selector is as simple as:

Definition

MarkdownHTMLPython

<|{dates}|date_range|>

<taipy:date_range>{dates}</taipy:date_range>

import taipy.gui.builder as tgb
...
tgb.date_range("{dates}")

The date range selector looks like this:

An on_change callback can be set to retrieve the user's selection:

def on_change(s: State, name: str, value: any):
    if name == "dates":
        # value[0] is set to the first selected date
        # value[1] is set to the first selected date

Selecting a range with times¶

You can set the with_time property to True to display the range time: the dates should then be instances of datetime.datetime.

Here is some code that defines the date range with specific time values:

import datetime

start_date = datetime.date(2023, 3, 26, 7, 37)
end_date   = datetime.date(2023, 3, 26, 19, 2)
dates = [start_date, end_date]

The control definition just has the with_time property set to True:

Definition

MarkdownHTMLPython

<|{dates}|date_range|with_time|>

<taipy:date_range with_time>{dates}</taipy:date_range>

import taipy.gui.builder as tgb
...
tgb.date_range("{dates}", with_time=True)

Here is how the date range selector looks like:

Custom labels¶

The label_start and label_end properties can be used to label the date fields to provide context to the user.

Here is how a hotel reservation application may declare a date range selector with appropriate labels for booking a given period:

Definition

MarkdownHTMLPython

<|{dates}|date_range|label_start=Check-in|label_end=Check-out|>

<taipy:date_range label_start="Check-in" label_end="Check-out">{dates}</taipy:date_range>

import taipy.gui.builder as tgb
...
tgb.date_range("{dates}", label_start="Check-in", label_end="Check-out")

Here is how the date range selector looks like: