4.32.2

Date picker

Interactive date input

Demo

API

Tag

Name Description
<s-datepicker> Custom Element, no content

Attributes

Name Value Required Description
open Boolean attribute

Opens the picker panel.
value ISO8601 date string

Sets value of datepicker.
mindate ISO8601 date string

Sets the earliest date (inclusive) available in the picker.
maxdate ISO8601 date string

Sets the latest date (inclusive) available in the picker.
disableddates JSON string of array of ISO8601 dates

Sets specific dates to be disabled in the picker. See Guidelines below.
required Boolean attribute

Marks the native <input> required.
disabled Boolean attribute

Disables the native <input>.
autofocusinput Boolean attribute

Autofocuses the native <input>.
inputname Name for input element

String to attach to name attribute on underlying input.
inputid ID for input element

Matches for attribute on associated label for accessiblity.
primaryformat Primary output formatting string (default "M/D/YYYY").

Sets the dayJS output format for the picker. This string is also added as the primary input template for users typing into the input field. Use / as the separator in your date string; the date picker will handle alternative separators (., space and -) when the user inputs them.

alternativeformats JSON-encoded list of alternative input formatting strings (default '["M/DD/YYYY", "MM/D/YYYY", "M/D/YYYY"]'). Use / as the separator in your date strings; the date picker will handle alternative separators (., space and -) when the user inputs them.

Sets alternative dayJS input formats for the picker.

pickertop Top position (in pixels) of the picker panel when opened

If the datepicker is placed in a container with overflow: hidden, the top of the picker panel may not be visible when opened. Use this attribute to set the desired top position of the panel.
pickerleft Left position (in pixels) of the picker panel when opened

If the datepicker is placed in a container with overflow: hidden, the left side of the picker panel may not be visible when opened. Use this attribute to set the desired left position of the panel.
i18n string

A stringified JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Classes

Name Description
width-auto Applies width: auto to the datepicker for situations in which the input should take up the full width of the container (e.g. the filters panel)
success Applies success styling and shows input-msg - see input page for more information
warning Applies warning styling and shows input-msg - see input page for more information
error Applies error styling and shows input-msg - see input page for more information

Properties

Name Value Required Description
open Boolean attribute

Opens the picker panel.
value ISO8601 date string or empty string Returns the selected date's value in ISO8601 format. If the input is cleared or the user enters invalid input, value is set to an empty string.
minDate ISO8601 date string

Sets the earliest date (inclusive) available in the picker.
maxDate ISO8601 date string

Sets the latest date (inclusive) available in the picker.
disabledDates Array of ISO8601 strings You can provide a formatted array to the <s-datepicker> element's <disableddates> attribute and specific dates will be disabled in the picker. see Guidelines below.
required Boolean attribute

Marks the native <input> required.
disabled Boolean attribute

Disables the native <input>.
autofocusInput Boolean attribute

Autofocuses the native <input>.
inputName Name for input element

String to attach to name attribute on underlying input.
inputId ID for input element

Matches for attribute on associated label for accessiblity.
primaryFormat Primary output formatting string (default "M/D/YYYY").

Sets the dayJS output format for the picker. This string is also added as the primary input template for users typing into the input field. Use / as the separator in your date string; the date picker will handle alternative separators (., space and -) when the user inputs them.

alternativeFormats JSON-encoded list of alternative input formatting strings (default '["M/DD/YYYY", "MM/D/YYYY", "M/D/YYYY"]'). Use / as the separator in your date strings; the date picker will handle alternative separators (., space and -) when the user inputs them.

Sets alternative dayJS input formats for the picker.

pickerTop Top position (in pixels) of the picker panel when opened

If the datepicker is placed in a container with overflow: hidden, the top of the picker panel may not be visible when opened. Use this attribute to set the desired top position of the panel.
pickerLeft Left position (in pixels) of the picker panel when opened

If the datepicker is placed in a container with overflow: hidden, the left side of the picker panel may not be visible when opened. Use this attribute to set the desired left position of the panel.
data-input-* string

Used to generate an attribute for the input inside the Datepicker component. e.g. data-input-aria-describedby, data-input-aria-invalid, data-input-aria-label.
i18n object

A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Events

Name Detail Description
s-select The date picker's inputId and the selected date's value in ISO8601 format are available on e.detail

Fired when a valid date is selected.
s-deselect The value property (set to an empty string) and the date picker's inputId are available on e.detail.

Fired when a non-required input is cleared (in the case of a required input being cleared, s-error will fire).

s-error The date picker's inputId, an invalid user input type, and associated message are available on e.detail

Fired when user input has bad format, is an invalid date, is outside of the acceptable range, or is cleared when input is required. See Validation section below for more detail.
s-open The date picker's inputId is available on e.detail

Fired when the date picker is opened.
s-close The date picker's inputId is available on e.detail

Fired when the date picker is closed.
s-blur The date picker's inputId is available on e.detail

Fired when the component loses focus.

Demo

API

Tag

Name
<SDatepicker>

Props

Name Value Required Description
open Boolean attribute

Opens the picker panel.
value ISO8601 date string

Sets value of datepicker.
minDate ISO8601 date string

Sets the earliest date (inclusive) available in the picker.
maxDate ISO8601 date string

Sets the latest date (inclusive) available in the picker.
disabledDates Array of ISO8601 date strings

Sets specific dates to be disabled in the picker.
required Boolean attribute

Marks the native <input> required.
disabled Boolean attribute

Disables the native <input>.
autofocus Boolean attribute

Autofocuses the native <input>.
inputName String

String to attach to name attribute on underlying input.
inputId String

ID for input element. Matches for attribute on associated label for accessibility.
primaryFormat String

A DayJS formatting string overriding the output mask for dates selected via the dialog box. Also provides an input template for values typed into the text box. Use / as the separator in your date string; the date picker will handle alternative separators (., space and -) when the user inputs them.

alternativeFormats Array of DayJS formatting strings

An array of DayJS formatting strings indicating, in addition to the primaryFormat value, other date formats that can be accepted by the text input. Use / as the separator in your date strings; the date picker will handle alternative separators (., space and -) when the user inputs them.

pickerTop Top position (in pixels) of the picker panel when opened

If the datepicker is placed in a container with overflow: hidden, the top of the picker panel may not be visible when opened. Use this prop to set the desired top position of the panel.
pickerLeft Left position (in pixels) of the picker panel when opened

If the datepicker is placed in a container with overflow: hidden, the left side of the picker panel may not be visible when opened. Use this prop to set the desired left position of the panel.
data-input-* string

Used to generate an attribute for the input inside the Datepicker component. e.g. data-input-aria-describedby, data-input-aria-invalid, data-input-aria-label.
i18n object

A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.
onS-select Function

Handles the s-select event fired when a valid date is selected. The date picker's inputId and the selected date's value in ISO8601 format are available on e.detail.

onS-deselect Function

Handles the s-deselect event fired when a non-required input is cleared. The value property (set to an empty string) and the date picker's inputId are available on e.detail. In the case of a required input being cleared, s-error will fire.

onS-error Function

Handles the s-error event fired when user input has bad format, is an invalid date, or is outside of the acceptable range. See Validation section above for more detail. The date picker's inputId, an invalid user input type and associated message are available on e.detail.

onS-open Function

Handles the s-open event fired when the date picker is opened. The date picker's inputId is available on e.detail.

onS-close Function

Handles the s-close event fired when the date picker is closed. The date picker's inputId is available on e.detail.

onS-blur Function

Handles the s-blur event fired when the component loses focus. The date picker's inputId is available on e.detail.

Classes

Name Description
width-auto Applies width: auto to the datepicker for situations in which the input should take up the full width of the container (e.g. the filters panel)
success Applies success styling and shows input-msg - see input page for more information
warning Applies warning styling and shows input-msg - see input page for more information
error Applies error styling and shows input-msg - see input page for more information

React implementation notes

Keeping Datepicker value synced with app state

If your app implements declarative changing or clearing of the Datepicker's value, you may run into situations in which the user's date selection does not match your app's state. It is good practice to keep app state updated based on the e.detail.value property emitted by the Datepicker's s-select event. For example: 

    
    const [ datepickerValue, setDatepickerValue ] = useState(initialValue);
    
    <SDatepicker
      value={datepickerValue}
      onS-select={
        (e) => setDatepickerValue(e.detail.value)
      }
    />

Skylab React links

General information about using our React package

Typescript

Exported types

// s-select event's e.detail export type SSelectData = { value: string; inputId: string; }; // s-close event's e.detail export type SCloseData = { inputId: string; }; // s-open event's e.detail export type SOpenData = { inputId: string; }; // s-deselect event's e.detail export type SDeselectData = { value: string; inputId: string; }; // s-error event's e.detail export type SErrorData = { type: string; message: string; invalidInput: string; inputId: string; };

i18n Strings

ID Description Default value
"datepicker.day.sunday", "datepicker.day.monday", etc. The days of the week. Sunday, Monday, etc.
"datepicker.month.january", "datepicker.month.february", etc. The months of the year. Use "datepicker.month.jan" instead January, February, etc.
"datepicker.month.jan", "datepicker.month.feb", etc. The abbreviated months of the year. Jan, Feb, etc.
"datepicker.error.outsideRange.mindateAndMaxdate" Error message indicating chosen date is out of range when both mindate and maxdate are set. Must include the strings {MINDATE} and {MAXDATE} as placeholders. This date is out of range. Select a date between {MINDATE} and {MAXDATE}.
"datepicker.error.outsideRange.mindateOnly" Error message indicating chosen date is out of range when only mindate is set. Must include the string {MINDATE} as a placeholder. This date is out of range. Select a date after {MINDATE}.
"datepicker.error.outsideRange.maxdateOnly" Error message indicating chosen date is out of range when only maxdate is set. Must include the string {MAXDATE} as a placeholder. This date is out of range. Select a date before {MAXDATE}.
"datepicker.error.invalidFormat" Error message indicating date has been entered in an incorrect format. Enter the date in MM/DD/YYYY format
"datepicker.error.disabledDate" Error message indicating selected date is disabled. This date is unavailable. Check the guidelines then try again.
"datepicker.error.isEmpty" Error message indicating datepicker is empty. A date is required. Enter a date in the mm/dd/yyyy format.
"datepicker.today" Text of "Today" button. Today
"datepicker.ariaLabel.previousNineYears" aria-label for "previous nine years" button. Display previous nine years
"datepicker.ariaLabel.nextNineYears" aria-label for "next nine years" button. Display next nine years
"datepicker.ariaLabel.chooseDate" aria-label for calendar icon button. Include {DATE} as placeholder for currently selected date, if any. {Varies depending on state of component. Example:} Choose Date, selected date is {DATE}, only some dates are available, other dates are inactive
"datepicker.ariaLabel.enterDate" aria-label for date input. Enter date
"datepicker.keyboardInstructions.monthYearUi" Instructions for using the month/year picker, to be announced by screen readers. Keyboard instructions: Arrow up or down to the desired month and press enter to select, then tab to year selector and arrow up or down through choices.
"datepicker.ariaLabel.previousYear" aria-label for "previous year" icon button. previous year
"datepicker.ariaLabel.previousMonth" aria-label for "previous month" icon button. previous month
"datepicker.ariaLabel.nextYear" aria-label for "next year" icon button. next year
"datepicker.ariaLabel.nextMonth" aria-label for "next month" icon button. next month
"datepicker.chooseMonthAndYear" Instructions for the month/year picker toggle button, to be announced by screen readers. Choose month and year
"datepicker.chooseDay" Instructions for the calendar toggle button, to be announced by screen readers. Choose day
"datepicker.cancel" "Cancel" button text. Cancel
"datepicker.done" "Done" button text. Done
"datepicker.apply" "Apply" button text. Apply

Guidelines

Accessibility

Ensure the for attribute on the associated label matches the inputid attribute on Datepicker.

Validation

Datepicker natively validates that input date is parseable and exists. If not, a s-error event is fired. The type key on e.detail will have one of the following values:

  • badFormat: user input is not formatted as a date, or the date is nonexistent (e.g. 2020-02-30)
  • outsideRange: user input is outside the range defined by the mindate and maxdate attributes
  • disabledDate: user input is a specific date that has been disabled by the disableddates attribute
  • isEmpty: user input is blank and the <Datepicker> has the required attribute (if the input is not required, the s-deselect event will fire when input is cleared.

There is also an associated message on e.detail that has been approved by Customer Learning to present to the user. When this error event is fired, set the error class on Datepicker and include input-msg as indicated in code sample above (see input page for further information on messaging). Additional validation can be performed within consuming app.

The value property on the <Datepicker> will be set to an empty string in the event of the s-error event firing.

Dates disabled

You can provide a formatted array to the <Datepicker> element's disabledDates prop (or the disableddates attribute in the Web Component) and specific dates will be disabled in the picker.

See disableddates attr value example:

// each date must have the format "YYYY-MM-DD" // array of dates must be stringified const disabledDates = "[\"2020-12-13\",\"2020-12-14\",\"2020-12-16\",\"2020-12-20\"]" document.querySelector('s-datepicker').setAttribute("disableddates", disabledDates)

Design

Design resources can be found on the Skylab design documentation site: skylab.avalara.com