Skip to main content

TimeframeSelector

Use the TimeframeSelector to let users select a timeframe by choosing a from and to value or one of the presets for common timeframes.

Import

import { TimeframeSelector } from '@dynatrace/strato-components-preview/forms';

Use cases

CodeSandbox

Control the state

The TimeframeSelector can be controlled, meaning that you can handle the selection state. To do so, you need to use the onChange prop to provide a handler that is called when the internal state changes. You also need to assign the value from the state to the TimeframeSelector by setting the value prop.

CodeSandbox

Set an initial value

When you create the state for controlling the timeframe selector, you may pass a TimeframeV2 to pre-fill the 'from' and 'to' inputs.

CodeSandbox

Pre-select a preset

If you want to pre-select one of the presets of the timeframe selector, initialize the state with an expression matching a preset.

CodeSandbox

Custom presets

Use the TimeframeSelector.Presets component to customize presets and show any timeframe inside the overlay if you want to add to the list of default preset items. The default presets are exported, so you can either add more items to the default ones or override them entirely. The preset list can display up to ten items. Also, if an invalid preset item is added, it will not be rendered and there will be a warning in dev mode that describes the issue in more detail.

CodeSandbox

Disable the timeframe selector

To disable the timeframe selector, add the disabled property.

CodeSandbox

Get timeframe details

If you need more information about the timeframe, you can take a look at the from and to objects returned by onChange.

CodeSandbox

Internationalization

The TimeframeSelector takes care of converting the ISO string to a local date/time for you, so there is no need to handle conversion yourself. The value passed to the onChange is converted back to an ISO string again or passed as an expression.

Use a customized trigger

By default, the TimeframeSelector comes with a trigger that ensures a consistent user experience. In exceptional cases, you may override the default trigger with a custom one. Make sure to communicate whether a timeframe is selected and, if so, the timeframe itself.

We automatically apply props to the provided custom trigger to ensure correct semantics. As an ideal pairing, use a button as the outermost HTML element inside the custom trigger.

CodeSandbox

We also provide a render function for the TimeframeSelector.CustomTrigger, giving you access to the displayValue that the TimeframeSelector would have applied. This enables you to customize the trigger component but still leverage the TimeframeSelectors internal logic. When using a render function here, you will need to make sure to spread the props to the trigger element to tie interactions back into the TimeframeSelector.

CodeSandbox

Show a custom placeholder

Use the TimeframeSelector.Trigger component to show a placeholder for the trigger button by adding the placeholder prop. If no option is selected, the placeholder value is shown by default. Notice that the clearable prop is used here to enable empty selection and that you can also add an aria-label to the trigger.

CodeSandbox

Show a custom display value

Use the TimeframeSelector.DisplayValue component inside the TimeframeSelector.Trigger component to customize the rendered value on the trigger button.

CodeSandbox

Enable selection clearing

This component provides a "Clear selection" button, which gives users the option to clear a selected timeframe. To display this button, the clearable prop has to be set to true.

CodeSandbox

Set the display precision

Change the default "minutes" display precision by setting the precision prop to either "seconds" or "milliseconds". This also sets the precision of the inputs shown in the overlay.

CodeSandbox

Set a min and max value

Define a min and max range by setting the min and max props to valid isoString dates. Use the FormField and FormFieldMessages to show the error if the initial date is outside this range. When opening the overlay, it would show a hint with the valid date range. If you enter a date outside this range, an error is shown instead.

CodeSandbox

Validate

This example shows how you can validate the TimeframeSelector using the react-hook-form package, which handles error messages. For connecting the form with the TimeframeSelector and validating, you need to register the field with custom error messages and use the useForm hook from react-hook-form. The TimeframeSelector can be submitted with a form and by default shows a set of error messages based on its value. Use the FormField and FormFieldMessages to show the errors. The validation of the DateTimeRangePicker used inside the overlay first happens when the input fields are touched and blurred, then on every subsequent change.

CodeSandbox

Migrate to TimeframeV2

The return value of the TimeframeSelector changed from Timeframe to TimeframeV2 with components-preview v0.113.1. The new type merges the former TimeframeDetails and values in one object. The access to the simple value switches from timeframe.from to timeframe.from.value.

The TimeframeSelector still accepts a simple notation where the value for from and to can be provided as string, e.g. { from: 'now()-1d'', to: 'now()' }. To get a TimeframeV2 object the _parseTime function from strato-components-preview can be used. This function will be replaced by parseTime function of the time module (@dynatrace-sdk/units/util-format/time) in the units-sdk eventually.

With the new type the units support was also aligned to Grail and, therefore, it dropped support for years (y), months (M) and weeks (w).

Still have questions?
Find answers in the Dynatrace Community