@axa-ch/dropdown

AXA Dropdown

This component represents a styled, enhanced replacement for native HTML <select>. The component is responsive, falling back to native look-and-feel under mobile viewports. Keyboard operation is supported.

Controlled-Component behaviour is supported.

Properties

defaultTitle

The String-valued attribute defaultTitle sets the initial title of the closed dropdown (default: first selected item).

Its intended use is primarily for native-HTML situations where server-generated items describe the choices proper, and a separate title like defaulttitle="Please select" prompts the user to make a choice.

value

The String-valued attribute value sets the selected dropdown option to the one with matching value. When reading value, it returns the currently selected value.

native

When true, the Boolean attribute native enforces native <select> UI look-and-feel for open dropdowns irrespective of window widths.

checkMark

When true, the Boolean attribute checkmark shows an animated checkmark to the right of the dropdown.

invalid

The boolean attribute invalid serves to indicate the validity of the element (default: false). If true, it sets the element into a visual error state.

error

The string-valued error provides error text as HTML. It sets the element into a visual error state, if invalid is true.

disabled

The Boolean attribute disabled disables the underlying element, both visually and functionally.

Note that a disabled dropdown will not participate in form submission.

maxHeight

When set to empty string (or used as boolean attribute), the String attribute maxHeight limits the height of an active dropdown to a sensible default and allows scrolling through its options.

When a number is given, the maxheight of the options will be limited to that value.

If you do not set this attribute, all the options will be displayed without any scrolling mechanism.

This property is most useful in space-constrained scenarios or with many options, e.g. in a country selector.

items

Is an array of objects to set the options of the dropdown. The objects must have a name and value set. See an example at the top of this Readme.

item	Details
name	The text that is displayed
value	The value that is submitted via form submit
selected	boolean: just set true to one of the options to preselect option

cropText

This removes the ellipsis dots when the value becomes too long to fully display on the dropdown element. It also reduces the paddings within the dropdown, for a more minified look.

Example: +41 Switzer... => +41 Switzerla

showValue

Display the value instead of the name (from the items array) as selected value in the dropdown.

Callback Properties

onChange

The function-valued attribute onChange can be used as a callback prop for React and other frameworks. The callback is invoked whenever the selected dropdown option changes. Its sole parameter item has the Typescript signature { value: string, name: string, label: string, index: number }.

target	Details
value	The currently selected value
name	The name of the element you set via property name
label	Visible text corresponding to value
index	0-based index of currently selected option

If a defaultTitle is set, the first element has index 1, because the title gets index 0.

Important: This attribute can also be used natively. However, in this case the event parameter passed conforms to the change event described below.

onFocus, onBlur

The function-valued attributes onFocus, onBlur can be used as a callback prop for React and other frameworks. The respective callback is invoked when the element receives or loses focus, respectively. Its only parameter is the original native event.

Events

axa-change, change

If not in controlled-component mode, two custom events axa-change and change are fired on <axa-dropdown> itself whenever the onChange callback from above gets invoked.

axa-change's event detail is the currently selected value (a string).

change's event detail is an object that is described above at onChange.

Both events do not bubble up through the DOM.