@axa-ch/dropdown
v12.0.4
Published
The dropdown component for the AXA Pattern Library
Downloads
477
Maintainers
Keywords
Readme
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.