Super date picker
EuiSuperDatePicker is a complex date picker that supports relative and absolute dates. It offers a convenient Quick select menu which includes Commonly used dates, Recently used date ranges and Auto refresh features.
Pass
start
and end
date times as strings in either datemath format (e.g.: now
, now-15m
, now-15m/m
) or as absolute date in the format YYYY-MM-DDTHH:mm:ss.SSSZ
. Use datemath to convert start and end strings into moment objects.
text code block:import dateMath from '@elastic/datemath'; const startMoment = dateMath.parse(start); // dateMath.parse is inconsistent with unparsable strings. // Sometimes undefined is returned, other times an invalid moment is returned if (!startMoment || !startMoment.isValid()) { throw new Error('Unable to parse start string'); } // Pass roundUp when parsing end string const endMoment = dateMath.parse(end, { roundUp: true }); if (!endMoment || !endMoment.isValid()) { throw new Error('Unable to parse end string'); }
Update button
When start
and end
change from interactions with Quick select, Commonly used, or Recently used date ranges,onTimeChange
will be immediately invoked. This is because these interactions set both start
and end
in a single event.
When start
and end
change from interactions with Absolute, Relative, and Now tabs,onTimeChange
will not be invoked. In these cases,onTimeChange
will be invoked when the user clicks the Update button. This gives users the ability to set both start
and end
before triggering onTimeChange
. Set showUpdateButton
to false
to immediately invoke onTimeChange
for all start
and end
changes.
More configurations
Instead of hiding completely, you can reduce the footprint of the update button to just an icon with showUpdateButton="iconOnly"
. You can further configure the button using updateButtonProps
, like setting the fill
to false
.
Quick select panels
EuiSuperDatePicker's quick select menu provides the user with single-click options for quick selection with the following panels.
commonlyUsedRanges
: A default set of common date ranges is automatically provided but can be overridden with this prop.recentlyUsedRanges
: Store the users previously submitted time ranges and pass them back to date picker with this props. It's best to limit this list to around 10 items.customQuickSelectPanels
: Accepts an array of panel objects as{ title: string, content: ReactElement }
.
You can also reduce the EuiSuperDatePicker to display just the quick select button and dropdown by passing isQuickSelectOnly={true}
. Be sure you display the rendered time period elsewhere in your interface.
Custom rendering
You can optionally pass the customQuickSelectRender
prop that passes default panels as arguments and allows you to re-order panels, omit certain panels entirely, or pass in your own fully custom content.
quickSelect
panelcommonlyUsedRanges
panelrecentlyUsedRanges
panelcustomQuickSelectPanels
refreshInterval
panelRefresh is on, interval set to 1 Seconds.
jsx code block:const customQuickSelectRender = ({ quickSelect, commonlyUsedRanges, recentlyUsedRanges, refreshInterval, customQuickSelectPanels, }) => ( <> {customQuickSelectPanels} {commonlyUsedRanges} {recentlyUsedRanges} {quickSelect} {refreshInterval} </> ); <EuiSuperDatePicker customQuickSelectRender={customQuickSelectRender} />
Sizing
By default the width
of the EuiSuperDatePicker is set to 'restricted'
which sets the size to a reasonable max-width necessary to display full start and end date strings.
You can adjust the width
by passing:
'full'
to expand the width to 100% of the parent'auto'
to grow and shrink as the contents does
The EuiSuperDatePicker also supports the compressed
form control option.
Auto refresh
By supplying a callback function to onRefreshChange
, the EuiSuperDatePicker will display the refreshInterval
configuration UI in the Quick select menu.
Set isAutoRefreshOnly
to true
to limit the component to only display auto refresh content. This is useful in cases where there is no time data but auto-refresh configuration is still desired.
However, since this is still the full EuiSuperDatePicker component it requires other props that may not be necessary for the refresh only UI. In this case, you can use the
EuiAutoRefresh component directly. You will just need to manage the refresh counter yourself.Elastic pattern with KQL
The following is a demo pattern of how to layout the EuiSuperDatePicker alongside Elastic's KQL search bar using EuiSearchBar and shrinking to fit when the search bar is in focus.
Locale
Locale formatting is achieved by using the locale
,timeFormat
, and dateFormat
props. The latter will take any moment()
notation. Check Date format by country for formatting examples.
Moment will try to load the locale on demand when it is used. Bundlers that do not support dynamic require statements will need to explicitly import the locale, e.g. import 'moment/locale/zh-cn'
. See the below demo TSX for examples.
Restricted range
To limit the range from which users can choose a date, you can use minDate
and maxDate
. By updating the date input values for start
and end
, users get immediate feedback on what range values are allowed.
Props
EuiSuperDatePicker
Prop | Description and type | Default value |
---|---|---|
Prop onTimeChange# | Description and type Callback for when the time changes. (props: OnTimeChangeProps) => void | Default value Required |
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Type: string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop commonlyUsedRanges# | Description and type Type: DurationRange[] | Default value |
Prop customQuickSelectPanels# | Description and type Type: QuickSelectPanel[] | Default value |
Prop customQuickSelectRender# | Description and type An optional render prop function that allows customizing the display of the Quick Select menu. (options: CustomQuickSelectRenderOptions) => ReactNode | Default value |
Prop dateFormat# | Description and type Specifies the formatted used when displaying dates and/or datetimes string | Default value 'MMM D, YYYY @ HH:mm:ss.SSS' |
Prop isAutoRefreshOnly# | Description and type Set isAutoRefreshOnly to true to limit the component to only display auto refresh content. boolean | Default value |
Prop isDisabled# | Description and type Accepts either a true/false boolean or an object configuration. The configuration will render the component as disabled, and allow you to boolean | { display: ReactNode; } | Default value |
Prop isLoading# | Description and type Type: boolean | Default value |
Prop isPaused# |