Getting started with date and time components

Learn how to display and manage date and time values in web apps.

You can use the following components to accept date or time inputs:

• Calendar Input
• Date Range
• Date Time
• Date
• Day
• Month
• Time
• Year

Calendar Input

Demo

Date Range

Demo

Date Time

Demo

Date

Demo

Day

Demo

Month

Demo

Time

Demo

Year

Demo

Features

Key features of date and time inputs include:

• First day configuration.
• Manual or mapped data sources.
• Time zone management.
• Input validation, including minimum and maximum values.
• Style configuration.

Specify content options

The Content section of the Inspector contains settings that control the content of an input field, such as:

• Default value
• Placeholder
• Label and caption

Define date and time format

For the Date, Date Time, Time, and Date Range components, you can define the Format setting of the user input component. This setting accepts a string in Unicode Locale Data Markup Language. Refer to the Unicode symbol reference for more information.

Regardless of the Format setting, the Default value of Date and Date Time must adhere to the ISO 8601 format. For example, "2024-01-01T12:00:00.555Z" would be an acceptable value.

Manage time zones

Components that display date time values support time zone offsets. When configured, the component displays a date time value (displayValue) to the user based on the selected offset without altering value itself. Similarly, when a user selects a different date time value, this changes the displayValue. Retool uses the same offset to calculate the actual value to use.

To manage time zones on these components, toggle Manage time zone in the Inspect tab of the right panel. The demo app below shows the difference in how date and time values appear when using managed and unmanaged time zones. Each component has the same underlying value.

Demo

To change the display of a date and time based on time zone, toggle on Manage time zone. You can manage the time zone in the following ways:

Local time

To display a time based on the end-user's local time zone, select Local time in the Display dropdown of the Inspector. This shows the timestamp adjusted for the user's local time, inferred from their browser or device.

Offset

To display a time based on a given time zone offset from UTC, in the Display field select the offset. In some locations, the offset for an area changes during daylight saving time (e.g., Eastern Time is -4:00 during daylight saving time and -5:00 otherwise).

Specific time zone

To display a time based on a given time zone:

1. In the Display field, select the JavaScript fx mode.
2. Enter {{ moment(self.value).tz('LOCAL_TIME_ZONE_NAME').format('Z') }}, where LOCAL_TIME_ZONE_NAME is the local time zone name, defined in the Moment library.

Time zones automatically adjust for daylight saving time.

Save values in a specified time zone

When working with dates and times, you can specify how to encode values with time zones. It can be useful to consistently save values in UTC and use local time zones only for display. You can set the component's Value to be UTC, a specific offset, or Local time.

Option	Description
UTC	Store values with no offset.
Specific offset, e.g., -5:00	Store values with the given offset, e.g., "1999-10-26T08:45:00.000-0500".
Local time	Store values with an offset inferred from the end user's local time, inferred from their browser or device.

Define mapped date values

The Day, Month, and Year components each include a Mode setting, which enables you to choose between Manual and Mapped data to define your input choices. When using the Mapped option, you can set the Data source to a query, transformer, or JavaScript.

For example, create a transformer with the following code, which defines the months of the year in Spanish. Save and run your transformer before continuing.

const spanishMonths = ["Enero", "Febrero", "Marzo", "Abril", "Mayo", "Junio", "Julio", "Agosto", "Septiembre", "Octubre", "Noviembre", "Diciembre"];

return spanishMonths;

Then, drag the Month component onto the canvas. Change the Mode to Mapped, and set the Data source to the transformer you just created. The Month component now enables you to choose between the months in Spanish.

Configure user interaction

The Interaction section of the Inspector contains settings that control user interaction and validation, such as:

• Event handlers, which listen for and handle interactions with your components.
• Validation rules, which define the types of user inputs that your components accept.

Customize appearance

You can customize the presentation of your component in the Spacing and Appearance sections of the Inspector. The settings available in the Appearance section depend on the type of component you use.

All components have a Hidden setting, which you can dynamically control with a truthy value that evaluates to true or false. You can also control the hidden property for a component using the .setHidden() method from event handlers and JavaScript queries.

You can also create custom style rules using the Styles setting. Each component has different styles that you can configure, but common ones include colors, fonts, and text styles. Use app-level or organization-level themes to set these styles across all components.