# Date range picker (DateRangePicker) Enables users to specify a date and time range. ## Properties ### ariaDescribedby > Adds `aria-describedby` to the component. If you're using this component within a form field, > don't set this property because the form field component automatically sets it. > Use this property if the component isn't surrounded by a form field, or you want to override the value > automatically set by the form field (for example, if you have two components within a single form field). > > To use it correctly, define an ID for each element that you want to use as a description > and set the property to a string of each ID separated by spaces (for example, `"id1 id2 id3"`). > Type: String Required: No ### ariaLabelledby > Adds `aria-labelledby` to the component. If you're using this component within a form field, > don't set this property because the form field component automatically sets it. > Use this property if the component isn't surrounded by a form field, or you want to override the value > automatically set by the form field (for example, if you have two components within a single form field). > > To use it correctly, define an ID for the element you want to use as label and set the property to that ID. > Type: String Required: No ### className > Adds the specified classes to the root element of the component. Type: String Required: No ### controlId > Specifies the ID of the native form element. You can use it to relate > a label element's `for` attribute to this control. > It defaults to an automatically generated ID that > is provided by its parent form field component. > Type: String Required: No ### dateOnly > Hides time inputs and changes the input format to date-only, e.g. 2021-04-06. > Do not use `dateOnly` flag conditionally. The component does not trigger the value update > when the flag changes which means the value format can become inconsistent. > > Default: `false`. > Type: Boolean Default: `false` Valid values: `true | false` Required: No ### disabled > Specifies that the component is disabled, preventing the user from > modifying the value. A disabled component cannot receive focus. Type: Boolean Default: `false` Valid values: `true | false` Required: No ### expandToViewport > Enabling this property will allow the dropdown to extend beyond its parent by using fixed positioning and > [React Portals](https://reactjs.org/docs/portals.html). > If you want the dropdown to ignore the `overflow` CSS property of its parents, > such as in a split view layout, enable this property. > However, use discretion. If you don't need to, we recommend you don't enable this property because fixed positioning results > in a slight, visible lag when scrolling complex pages. Type: Boolean Default: `false` Valid values: `true | false` Required: No ### i18nStrings > An object containing all the necessary localized strings required by the component. Type: ``` DateRangePickerProps.I18nStrings { absoluteModeTitle: string applyButtonLabel: string ariaDescribedby?: string ariaLabel?: string ariaLabelledby?: string cancelButtonLabel: string clearButtonLabel: string customRelativeRangeDurationLabel: string customRelativeRangeDurationPlaceholder: string customRelativeRangeOptionDescription: string customRelativeRangeOptionLabel: string customRelativeRangeUnitLabel: string dateTimeConstraintText?: string endDateLabel: string endTimeLabel: string formatRelativeRange: ( value: DateRangePickerProps.RelativeValue ) => string formatUnit: ( unit: DateRangePickerProps.TimeUnit, value: number ) => string nextMonthAriaLabel: string previousMonthAriaLabel: string relativeModeTitle: string relativeRangeSelectionHeading: string startDateLabel: string startTimeLabel: string todayAriaLabel: string } ``` Required: Yes ### id > Adds the specified ID to the root element of the component. Type: String Required: No ### invalid > Overrides the invalidation state. Usually the invalid state > comes from the parent `FormField` / `awsui-form-field` > component, however sometimes you need to override its > state when you have more than one input within a > single form field. Type: Boolean Default: `false` Valid values: `true | false` Required: No ### isDateEnabled > A function that defines whether a particular date should be enabled > in the calendar or not. Note that disabling a date in the calendar > still allows users to enter this date via keyboard. We therefore > recommend that you also validate these constraints client- and > server-side, in the same way as for other form elements. Type: (date: Date) => boolean Default: `() => true` Required: No ### isValidRange > A function that defines whether a particular range is valid or not. > Ensure that your function checks for missing fields in the value. > Type: ``` ( value: DateRangePickerProps.Value | null ) => DateRangePickerProps.ValidationResult ``` Default: `() => ({ valid: true })` Required: Yes ### locale > The locale to be used for rendering month names and defining the > starting date of the week. If not provided, it will be determined > from the page and browser locales. Supported values and formats > are as-per the [JavaScript Intl API specification](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation). Type: String Default: `''` Required: No ### placeholder > Specifies the placeholder text that is rendered when the value is empty. Type: String Required: No ### rangeSelectorMode > Determines the range selector mode as follows: > * `default` for combined absolute/relative range selector. > * `absolute-only` for absolute-only range selector. > * `relative-only` for relative-only range selector. > By default, the range selector mode is `default`. > Type: String Default: `'default'` Valid values: `default | absolute-only | relative-only` Required: No ### readOnly > Specifies that the component is read-only, preventing the user from > modifying the value. A read-only component can receive focus. Type: Boolean Default: `false` Valid values: `true | false` Required: No ### relativeOptions > A list of relative time ranges that are shown as suggestions. Type: ReadonlyArray<DateRangePickerProps.RelativeOption> Default: `[]` Required: Yes ### showClearButton > Specifies whether the component should show a button that > allows the user to clear the selected value. Type: Boolean Default: `true` Valid values: `true | false` Required: No ### startOfWeek > Starting day of the week. [0-6] maps to [Sunday-Saturday]. > By default the starting day of the week is defined by the locale, > but you can override it using this property. Type: Number Required: No ### timeInputFormat > Specifies the format of the time input for absolute ranges. > Use to restrict the granularity of time that the user can enter. > > Has no effect when `dateOnly` is true. > Type: String Default: `'hh:mm:ss'` Valid values: `hh | hh:mm | hh:mm:ss` Required: No ### timeOffset > The time offset from UTC in minutes that should be used to > display and produce values. > Has no effect when `dateOnly` is true. > > Default: the user's current time offset as provided by the browser. > Type: Number Default: `getBrowserTimezoneOffset()` Required: No ### value > The current date range value. Can be either an absolute time range > or a relative time range. Type: DateRangePickerProps.Value | null Required: Yes ## Events ### onBlur > Fired when keyboard focus is removed from the UI control. Detail type: ``` Null ``` Cancelable: No ### onChange > Fired whenever a user changes the component's value. > The event `detail` contains the current value of the field. Detail type: ``` DateRangePickerProps.ChangeDetail { value: DateRangePickerProps.Value | null } ``` Cancelable: No ### onFocus > Fired when keyboard focus is set onto the UI control. Detail type: ``` Null ``` Cancelable: No ## Ref functions ### focus > Sets the browser focus on the UI control ## License Summary The documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the LICENSE file.