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.

There is currently only a controlled version of the TimeframeSelector available. To use the timeframe selector, create a state holding the current value of the timeframe selector and pass the value to the timeframe selector. Use the onChange prop to provide a handler that is called when the internal state of the timeframe selector changes.

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

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). For an easier migration to the new supported values, a helper function _migrateDeprecatedExpression is provided. The function converts expressions that contain the old units into an approximation of the time in days. So for example from now()-1M to now()-30d.

Props

TimeframeSelectorProps

Signature:

export declare type TimeframeSelectorProps = & ( | );

TimeframeSelectorBaseProps

extends, , ,
NameTypeDefaultDescription
clearable?
falseShows the "Clear selection" button if set to true.
readOnly?
falseDetermines whether the component is in read-only mode, which means the overlay doesn't open and the onChange isn't called.
min?
-The ISODatetime string of the earliest datetime that can be configured.
max?
-The ISODatetime string of the latest datetime that can be configured.
precision?
| |
'minutes'The precision of the time shown in the display value.

TimeframeSelectorControlledProps

NameTypeDefaultDescription
value
<{ from: ; to: ; }> | <> |
-The controlled value of the timeframe selector, containing the 'from' and 'to' timeframe details.
onChange
(value: | ) =>
-Handler gets called if value state has changed.

TimeframeSelectorUncontrolledProps

NameTypeDefaultDescription
defaultValue?
<{ from: ; to: ; }> | <> |
-The default, uncontrolled value of the timeframe selector, containing the 'from' and 'to' timeframe details.
onChange?
(value: | ) =>
-Handler gets called if value state has changed.

TimeframeSelector presets components

TimeframeSelector.Presets

The TimeframeSelector.Presets component is used to render the list of preset items shown in the overlay.

TimeframeSelectorPresetsProps

extends, , ,
NameTypeDefaultDescription
children?
-Children shown inside the presets list.A default list of presets is shown if no children are set.

TimeframeSelector.PresetItem

The TimeframeSelector.PresetItem component is used to render a preset item to the list of presets shown in the overlay. This needs to be used inside the TimeframeSelector.Presets component.

TimeframeSelectorPresetItemProps

extends<>, , ,
NameTypeDefaultDescription
value
{ /** Start of the time frame. */ from: ; /** End of the time frame. */ to: ; }
-The value of the timeframe preset.

TimeframeSelector trigger components

TimeframeSelector.Trigger

The TimeframeSelector.Trigger component is used to render the trigger that opens or closes the overlay.

TimeframeSelectorTriggerProps

Signature:

export declare type TimeframeSelectorTriggerProps = & & & & { /** * The placeholder text displayed in the TimeframeSelector.Trigger. */ placeholder?: ; };

TimeframeSelector.DisplayValue

TimeframeSelectorDisplayValueProps

Signature:

export declare type TimeframeSelectorDisplayValueProps = <>;

TimeframeSelector.CustomTrigger

TimeframeSelectorCustomTriggerProps

Signature:

export declare type TimeframeSelectorCustomTriggerProps = & & & { /** Elements to be displayed in the CustomTrigger. */ children: ; };
Still have questions?
Find answers in the Dynatrace Community