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.
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.
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.
When true, the Boolean attribute native enforces native <select> UI look-and-feel for open dropdowns irrespective of
window widths.
When true, the Boolean attribute checkmark shows an animated checkmark to the right of the dropdown.
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.
The string-valued error provides error text as HTML. It sets the element into a visual error state, if invalid is true.
The Boolean attribute disabled disables the underlying element, both visually and functionally.
Note that a disabled dropdown will not participate in form submission.
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.
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 |
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
Display the value instead of the name (from the items array) as selected value in the dropdown.
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.
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.
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.