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
The default min and max values of the TimeframeSelector are set according
to the current Grail limitations regarding timeframes. You can define a custom
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.
Disable the TimeframeStepper
The TimeframeStepper feature allows users to shift timeframes forward and
backward using two buttons and is enabled by default. The behavior of the
stepper varies based on the type of timestamps provided. Relative timestamps
will shift relative to the current time. Absolute timestamps and mixed
timestamps will shift by the total difference between the timestamps. The
stepper respects minimum and maximum settings, ensuring that the time doesn't
exceed these boundaries. However, you can disable the automatically enabled
TimeframeStepper by setting the stepper prop to false.
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
parseTimeAsTimeValue function from @dynatrace-sdk/units 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).