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
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.
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.
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.
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.
Disable the timeframe selector
To disable the timeframe selector, add the disabled property.
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.
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.
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.
Show a custom display value
Use the TimeframeSelector.DisplayValue component inside the
TimeframeSelector.Trigger component to customize the rendered value on the
trigger button.
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.
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.
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.
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.
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
, , , , | Name | Type | Default | Description |
|---|---|---|---|
clearable? | false | Shows the "Clear selection" button if set to true. | |
readOnly? | false | Determines 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
| Name | Type | Default | Description |
|---|---|---|---|
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
| Name | Type | Default | Description |
|---|---|---|---|
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
, , , | Name | Type | Default | Description |
|---|---|---|---|
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
<>, , , | Name | Type | Default | Description |
|---|---|---|---|
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: ;
};