Skip to main content

Select

shadow

The Select element extends the capabilities of the standard HTML select element to provide an enhanced user experience. It supports both single and multiple option selection using the multiple attribute. It offers advanced features such as clearable content with the clearable attribute, searching through options with find, and lazy loading to optimize performance with the lazy attribute. When multiple options are selected, the selected items are displayed as chips with a configurable maximum number of items displayed. The component also supports dynamic loading of options from external sources via the Options element.

Basic usage​

By default, the selection allows the user to select only one option. Including the Icon element will also display the selected icon next to the option.

Selecting multiple items​

Adding the multiple attribute allows the user to select multiple options.

Clearable​

Adding the clearable attribute allows the user to remove all selected options by clicking on the icon.

Disabled​

Adding the disabled attribute prevents the user from interacting with Select.

Dynamic list of options​

Using the Options component, a dynamically generated list of options is also supported, which is asynchronously retrieved from the specified URL. When no options are returned, or when search produces no match, the dropdown shows an empty state message. This message is resolved from the wj.select.empty localization key. To change it in the library, update the matching language file in packages/translations, for example packages/translations/sk-sk.js or packages/translations/en-gb.js. The active translation is selected from lang on the component or one of its ancestors.

export const enGb = {
    // ...
    'wj.select.empty': 'No data',
};

Standard​

Adding the standard attribute will display the Select in the style of a standard HTML Select.

Lazy loading​

Adding the lazy attribute will load options only when needed. This can be useful for large amounts of options or when loading from external sources.

Find​

Adding the find attribute displays an input field that allows the user to search for options in the list. The user can enter text and the list is automatically filtered according to the text entered.

By combining the lazy and find attributes, options are only loaded when the user starts typing in the input field. This can be useful for large amounts of options or when loading from external sources.

When to use​

Use wje-select when users need to enter values, choose options, or trigger form-related actions.

When not to use​

Do not use it as a decorative element without interaction. Prefer presentational components in that case.

Accessibility​

Always provide a label (label/aria-label), keep keyboard support, and surface clear validation feedback.

Best Practices​

  • Keep validation rules and error behavior consistent across the entire form.
  • Show loading or disabled states during async operations.
  • Split complex forms into smaller sections with immediate feedback.

Attributes and Properties​

active​

DescriptionControls whether the select dropdown is currently open.
Attributeactive
Typeboolean
Default-

customErrorDisplay​

DescriptionGetter for the customErrorDisplay attribute.
Attributecustom-error-display
Typeboolean
Defaultfalse

disabled​

DescriptionSets or removes the disabled state for the associated elements.
Attributedisabled
Typeboolean
Defaultfalse

lazy​

DescriptionSets the lazy attribute on the element. If the provided value is truthy, the lazy attribute is added. If the value is falsy, the lazy attribute is removed.
Attributelazy
Typeboolean
Defaultfalse

maxHeight​

DescriptionSets the maximum height value for the element. If a value is provided, it sets the 'max-height' attribute on the element. If no value is provided, it removes the 'max-height' attribute from the element.
Attributemax-height
Typestring｜null
Defaultauto

maxOptions​

DescriptionSets the maximum number of options allowed.
Attributemax-options
Typenumber ｜ object
Default1

noSize​

DescriptionSets or removes the 'no-size' attribute on an element.
Attributeno-size
Typeboolean
Defaultfalse

offset​

DescriptionGets the value of the offset attribute of the current element. If the offset attribute is not present, returns a default value of '0'.
Attributeoffset
Typestring
Default5

readonly​

DescriptionChecks if the 'readonly' attribute is present on the element.
Attributereadonly
Typeboolean
Defaultfalse

trigger​

DescriptionSets the trigger value.
Attributetrigger
Typestring
Defaultclick

value​

DescriptionSets the value for the form field. Converts the input value into a FormData object if it is not already an array, splitting by spaces if necessary, and sets the internal form value as well as the selected values.
Attributevalue
Typestring｜Array
Default-

Events​

NameDescription
wje-popup:content-readyEmitted when the wje-popup:content-ready event is dispatched.
wje-select:changeEmitted when the component value changes.

Methods​

getAllOptions​

DescriptionReturns all the options as HTML.
Signature() => NodeList

addOption​

DescriptionAdds a new option to the component.
Signature(optionData: object, silent?: boolean, map?: object) => void

addOptions​

DescriptionAdds one or more options to a collection. If the input is an array, it adds each option within the array. Otherwise, it adds a single option.
Signature(optionsData: Array ｜ object, silent?: boolean, map?: object) => void

selectOption​

DescriptionSelects an option from the available options within the component.
Signature(value: string, silent?: boolean) => void

selectOptions​

DescriptionSelects multiple options based on the provided values. If a single value is provided, it selects that option. If an array of values is provided, it iterates through the array and selects each option.
Signature(values: any｜any[], silent?: boolean) => void

clearSelections​

DescriptionClears all selected options and resets selections. The method ensures that all options are deselected, updates the internal state, validates the selections, propagates the validation status, and indicates invalid state if necessary.
Signature() => void

CSS Shadow Parts​

No CSS shadow parts available for this component.

CSS Custom Properties​

No CSS custom properties available for this component.

Slots​

No slots available for this component.

Content