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 panelcustomQuickSelectPanelsrefreshInterval 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# | Description and type Type: boolean | Default value true |
Prop width# | Description and type Sets the overall width by adding sensible min and max widths.
"auto" | "restricted" | "full" | Default value 'restricted' |
Prop compressed# | Description and type Reduces overall height to compressed form size boolean | Default value |
Prop locale# | Description and type Used to localize e.g. month names, passed to LocaleSpecifier | Default value |
Prop onFocus# | Description and type Triggered whenever the EuiSuperDatePicker's dates are focused FocusEventHandler | Default value |
Prop onRefresh# | Description and type Callback for when the refresh interval is fired. (props: OnRefreshProps) => void | Default value |
Prop onRefreshChange# | Description and type Callback for when the refresh interval changes. ApplyRefreshInterval | Default value |
Prop recentlyUsedRanges# | Description and type Type: DurationRange[] | Default value |
Prop refreshInterval# | Description and type Refresh interval in milliseconds number | Default value 1000 |
Prop refreshMinInterval# | Description and type Minimum refresh interval in milliseconds number | Default value 0 |
Prop refreshIntervalUnits# | Description and type By default, refresh interval units will be rounded up to next largest unit of time If you do not want this behavior, you will need to store the user-set "s" | "m" | "h" | Default value |
Prop start# | Description and type Type: string | Default value 'now-15m' |
Prop end# | Description and type Type: string | Default value 'now' |
Prop minDate# | Description and type Defines min. date accepted as a selection (in moment format) moment.Moment | Default value |
Prop maxDate# | Description and type Defines max. date accepted as a selection (in moment format) moment.Moment | Default value |
Prop timeFormat# | Description and type Specifies the formatted used when displaying times string | Default value 'HH:mm' |
Prop utcOffset# | Description and type Type: number | Default value |
Prop showUpdateButton# | Description and type Set showUpdateButton to false to immediately invoke onTimeChange for all start and end changes. boolean | "iconOnly" | Default value true |
Prop isQuickSelectOnly# | Description and type Hides the actual input reducing to just the quick select button. boolean | Default value |
Prop updateButtonProps# | Description and type Props passed to the update button EuiSuperUpdateButtonProps EuiSuperUpdateButtonProps | Default value |
Prop quickSelectButtonProps# | Description and type Props passed to the quick select button Partial<Omit<EuiButtonEmptyPropsForButton, "children" | "isLoading" | "isDisabled">> | Default value |
Prop canRoundRelativeUnits# | Description and type By default, relative units will be rounded up to next largest unit of time If you do not want this behavior and instead wish to keep the exact units boolean | Default value |