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
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.
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.
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).