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.
width	Union[str, int]	None	The width of the date_range element.
on_change	Union[str, Callable]		A function or the name of a function that is triggered when the value changes. The callback function receives the following parameters: state (State): the state instance. var_name (str): the bound variable name. value (Any): the updated value.
propagate	bool	App config	Determines whether the control's value is automatically reflected in the bound application variable. The default value is defined at the application configuration level by the propagate configuration option. If True, any change to the control's value is immediately reflected in the variable.
active	bool dynamic	True	Indicates if this element is active. If False, the element is disabled, and user interaction is not allowed.
id	str		The identifier assigned to the rendered HTML component. This can be used in callbacks or to target the element for styling.
properties	dict[str, Any]		A dictionary of additional properties that can be set to the element.
class_name	str dynamic		A space-separated list of CSS class names to be applied to the generated HTML element. These classes are added to the default taipy-date_range class.
hover_text	str dynamic		The text that is displayed when the user hovers over the 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.

Usage

Selecting a date range

See the entire code for this example

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:

Date range selector

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

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

Selecting a range with times

See the entire code for this example

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.datetime(2023, 3, 26, 7, 37)
end_date   = datetime.datetime(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:

Date range selector with time

Custom labels

See the entire code for this example

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:

Labels on the date fields

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.

The generated HTML elements have additional specific classes:

• The date picker element for the start date is assigned the "taipy-date-range-picker" and "taipy-date-range-picker-start" classes.
• The date picker element for the end date is assigned the "taipy-date-range-picker" and "taipy-date-range-picker-end" classes. classes.

Changing colors

See the entire code for this example

The start and end date pickers contain a date input field with the "MuiInputBase-root" class.

Below are examples of CSS rules that modify the colors of the date range control:

.taipy-date-range {
    .taipy-date-range-picker-start {
        .MuiInputBase-root {
            & {
                color: green;
            }

            .MuiIconButton-root: {
                color: green;
            }
        }
    }

    .taipy-date-range-picker-end {
        .MuiInputBase-root {
            & {
                color: orange;
            }

            .MuiIconButton-root {
                color: orange;
            }
        }
    }
}

When these CSS rules are applied, the date range control is styled as shown below:

Styling the date range control