This package has been deprecated

Author message:

Please use the new scope @axa-ch-webhub-cloud

@axa-ch/datepicker

AXA Datepicker

Properties

locale

The string-valued locale defines region-specific date rendering preferences such as separators etc. (default: de-CH).

Note 1: Week start is hardwired to Monday, only its translation is influenced by locale.

Note 2: The locale it-CH is mapped to date format de-CH. Example: 8.1.1982

year

The number-valued year defines the start year of the datepicker (default: current year). If year is non-empty but does not match any entries at allowedyears, the first entry of allowedyears will be set as year attribute to avoid an 'empty' datepicker that would not show any days to select.

month

The number-valued month defines the start month of the datepicker (default: current month).

Note: Numeric months are zero-based, i.e. January is 0.

day

The number-valued day defines the start day of the datepicker (default: current day).

Note: Numeric days ≤ 0 wrap around into the end of the previous month (cf. MDN Date.setDate).

inputfield

Boolean-valued inputfield toggles visibility of a free-form date-input field (default: false).

Input-field content is validated.

allowedyears

The array-valued allowedyears specifies the years that will be visible in the date-picker dropdown. If you do not specify any allowedyears, the year property value will be added to allowedyears to avoid an empty year dropdown.

Both individual years [2019,2020], year ranges ["1989-2010"], and a mix of the two ["1989-2010", 2012, 2014] are supported.

placeholder, monthtitle, yeartitle, invaliddatetext

These string-valued properties are all used to internationalize various texts in <axa-datepicker>:

• placeholder is the placeholder text of the free-form date-input field (default: Please select a date).

• monthtitle is the text shown on the month dropdown when nothing is preselected (default: Choose Month).

• yeartitle is the text shown on the year dropdown when nothing is preselected (default: Choose Year).

• invaliddatetext is the text shown under the free-form date-input field when date validation fails (default: Invalid date).

value

The string-valued value sets the content of the free-form date-input field. When reading from value, it contains the date-input field's current content.

This property is especially relevant for controlled-component behaviour under React.

defaultValue

The string-valued defaultValue sets the initial content of the free-form date-input field. This property is only available under React.

It is intended to be used in conjunction with date, which does not auto-reflect to the date-input field ( rather, only user-initiated input does).

Note: initial refers to the firstUpdated lifecycle point of the component's internal lifecycle — the datepicker by construction is unaware of external lifecycles such as React's.

As a consequence, React developers should avoid the pitfall of unnecessarily recreating a new instance of the datepicker from scratch on every property update, especially for date changes. Failure to do so not only incurs a performance penalty, it also causes defaultValue to be imposed after every (re)creation. This may in turn create the false impression that the datepicker is not reactive to property changes, since its input-field value would be always that of defaultValue.

name

The string-valued name sets the name attribute of the free-form date-input field.

This property is especially relevant for using <axa-datepicker> inside a <form>.

outputdate

The string-valued outputdate (read-only) reflects the currently selected date in the format of the current locale.

date

The date property takes a Date object to set the current internal date of the datepicker.

Setting date implies automatically derived values for year, month, and day.

Defining a date property does not imply controlled-component behaviour.

Likewise, date is not automatically reflected to the date input field. Rather, only user input is.

invalid

Boolean invalid, when set to true, forces showing the error message set with invaliddatetext even when user input is valid — except when invaliddatetext is itself empty (technically, falsy).

The intended use case is to easily convey external validation failure, e.g. when an application decides the entered date is outside a permissible date range.

width (has to be set as inline-style)

You can set the width of the datepicker with inline-style. It allows to override the intrinsic dimensions of the datepicker. Note that there is a minimum of 260px if you use the datepicker with an input-field.

Example values:

• 90%: Sets percentage value of width of parent element.
• 400px: Sets px value of width of parent element.

Example native:

• style="width:500px"

Example react:

• style={{width:"500px"}}

label

String-valued label sets a label text above the input-field part of the datepicker.

required

Boolean required, when true, adds a star after the label text to visually convey to the user that filling this input-field datepicker is mandatory.

disabled

Boolean disabled, when true, disables the datepicker, both in terms of keyboard input and dropping down the datepicker proper.

This state is visually conveyed to the user via suitable grey colours.

checkMark

Boolean checkMark, when true, paints a checkmark icon after the datepicker.

Its intended use is in conjunction with external validation.

autofocus

Boolean autofocus, when true, sets keyboard focus on the input field after initial rendering of a datepicker configured for inputfield mode.

Callback Properties

onChange

The function-valued attribute onChange can be used as a callback prop for React and other frameworks. The callback is invoked on every input event emitted from the free-form date-input field. It is also invoked whenever the user presses the OK button to accept a date selected from the calendar.

This property is especially relevant for controlled-component behaviour under React.

An input event with target:{value} is passed as parameter 1 of the callback, in which value represents the new date-input string from the free-form date-input field.

Note that due to input event characteristics, pasting date strings into the free-form date-input field is supported (unlike in native <input type="date">).

onDateChange

The function-valued attribute onDateChange can be used as a callback prop for React and other frameworks.

The callback is invoked once for every user input change that results in a valid date under the current locale and allowedyears restrictions.

A valid Date object is passed as parameter 1 of the callback.

onFocus, onBlur

The function-valued attributes onFocus, onBlur can be used as callback props for React and other frameworks.

The respective callbacks are invoked with the original native event as their only parameter whenever the free-form date-input field receives or loses focus. As such, they only make sense together with the inputfield attribute.

onInputfieldKeyUp

The function-valued attribute onInputfieldKeyUp can be used as a callback prop for React and other frameworks.

The callback is invoked once for every user input at the inputfield. The keyUp event object is passed as parameter 1 of the callback. As such, it only make sense together with the inputfield attribute.

Events

The custom events axa-change and change are fired on <axa-datepicker> itself whenever onDateChange fires (see above). Their event.detail value is the value property for axa-change (a string), and a {value, date, name} object for change.

Both events do not bubble up through the DOM.

The custom event axa-input is fired on <axa-datepicker> itself whenever the free-form date-input field's input event fires. Its event.detail value is a {value, date, name} object, with value being the current input-field value, date being a corresponding Date instance if valid (null otherwise), and name as defined above.

The intended usage is for native applications using the datepicker in conjunction with e.g. inline event listeners.

This functionality is not available in controlled-component mode.