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
Typeany
Default-

disabled​

DescriptionRetrieves the current state of the 'disabled' attribute.
Attributedisabled
Typeboolean
Default-

readonly​

DescriptionChecks if the 'readonly' attribute is present on the element.
Attributereadonly
Typeboolean
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

selectionChanged​

DescriptionHandles changes in the selection for a component, updating internal values, input fields, and visual presentation (like chips or slots) as per the given selection options.
Signature(options: Array｜null, length: number) => void

selections​

DescriptionHandles the logic for updating selections based on the current selected options, updating chips content, and dispatching change events if necessary.
Signature(silence?: boolean) => void

counter​

DescriptionUpdates the counter element to reflect the current state of selected values relative to the maximum allowed options. If the maximum options are selected, the counter element is removed. If it does not already exist and needs to be displayed, it is created.
Signature() => void

getChip​

DescriptionCreates and returns a chip element with specified properties and a label.
Signature(option: object) => HTMLElement

htmlOption​

DescriptionGenerates an HTML option element based on the provided item and mapping.
Signature(item: object, map?: object) => HTMLElement

htmlSelectedItem​

DescriptionReturns the provided item.
Signature(item: any) => any

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

optionCheckSlot​

DescriptionClones and appends an icon with the "check" slot to the specified option element. If the option already contains a custom element with slot="check" (e.g. <wje-status slot="check">), it is left untouched and no template icon is added.
Signature(option: HTMLElement) =&gt; 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() =&gt; 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