Selectable plugin

Frontfire UI allows making the children of any element selectable. This looks like a regular select box and also allows multiple selection. It is by default used as a nicer replacement of native <select> elements where it can use a dropdown select box.

This plugin is available in the Minimal and Complete bundles.

This plugin depends on the plugins: dropdown

Select box

The children of any element can be made selectable by clicking on them. The selected items are highlighted. The select box is focusable and the selection can be changed with the arrow keys when it has the focus.

Add the selectable CSS class to an element, or call the selectable() plugin method on it, to add the selection behaviour.

The colours of hovered and selected items can be customised with the CSS variables that start with “--selectable-”. The border and background can be customised with some of the CSS variables that start with “--textbox-”.

Search text

When typing printable characters, the first item whose text starts with the typed search text will be selected. The search text is reset when opening or closing the dropdown, pressing another navigation key or the Escape key, or 3 seconds after the last input.

The matching search text will also be underlined in the selected item. This is based on the item’s plain-text content so it removes any HTML formatting while the underlining is active. If an item matched the search but more text was typed for which there is no match, the underline changes its colour.

The underline style can be changed by redefining the selectable-search-match CSS class. The non-matching style can be changed by redefining the selectable-search-no-match CSS class. The underline feature can be disabled by the showSearchMatch option.

Multiple selection

Multiple items may be selected at the same time with the multiple option. It handles clicking an item with the Ctrl or Shift key pressed.

Toggle selection

Items can be selected or deselected individually by a single click instead of pressing the Ctrl key, by setting the toggle option. This implies multiple selection.

HTML <select> element

The select box can be enabled and disabled by setting the disabled property of the HTML <select> element by any means (through Frontfire or the native DOM API). Since it was visibly replaced by the new element, that element will follow the disabled state automatically.

The select box can be shown and hidden by setting the Frontfire.visible property of the HTML <select> element. Alternatively, the Frontfire methods show(), hide() and toggle() can be called. Other ways like manipulating the style.display property directly will not work. Since it was visibly replaced by the new element, that element will be shown or hidden instead of the select element.

When a dropdown is used and multiple or toggle selection is allowed, the dropdown does not close when clicking on an item. It remains open so that more items can be selected. To close the dropdown, click either on the button that opened the dropdown, anywhere else outside the dropdown, or (not for toggle selection) double-click on an item to select only that one.

Selection control

Custom selectables

The selected items of non-HTML selectables can be controlled with plugin methods. The getSelection() method returns all selected elements. The selectItem() method selects a single element, deselecting all others. The selectNone() and selectAll() methods deselect or select all list items.

When the selection changes (from user interaction or by calling any of these methods), the change event is triggered on the selectable element.

To prevent the user to select certain element, they can be disabled by adding the disabled attribute to the child element. Disabled items can still be selected by code.

HTML select

With HTML <select> elements, the same as above applies. The selectItem() method needs the <option> element as argument then. The generated UI elements generally do not appear in the API here.

Additionally, the <option> elements’ selected property can be changed directly. In this case, a change event must be triggered on the select element so that the UI can be updated accordingly because there is no way to automatically detect such a property change.

When the selection changes (from user interaction or by calling any of these methods), the change event is triggered on the HTML <select> element (not its UI representation). You generally only interact with the <select> element and its children here and don’t care about its presentation elements.

The same applies to <select> elements that are displayed as dropdown (without the size attribute).

Child updating

Custom selectables

To add or remove items to the selectable, it is sufficient to add or remove child elements from the container element. The new and removed children are automatically detected and prepared.

If a selected child was removed and not added back in the same microtask (i.e. before await or setTimeout), a change event is asynchronously triggered on the selectable element and, if the required option is set, another child will be selected if possible.

HTML select

To add or remove items to the HTML <select> element, it is sufficient to add or remove child <option> elements from the select element. The new and removed options are automatically detected and displayed.

If a selected option was removed and not added back in the same microtask (i.e. before await or setTimeout), a change event is asynchronously triggered on the <select> element and, if the required attribute is set, another option will be selected if possible.

HTML content and summaries

Another advantage of the selectable over a native <select> element is that it can display HTML content in the options. This can be used to include icons or formatting of the option texts. The HTML content is specified in the data-html attribute of each <option>.

The plain text content of the <option> element should still be set as it is used for the search function and may be picked up by assistive or automation technologies.

The HTML content will also be displayed in the dropdown button. To reduce the complexity of it and reduce the complaxity of the currently selected value, a summary can be defined for each option. That summary will be displayed in the button instead of the full content. Using summaries is independent from using HTML content. The summary can also be specified with HTML code.

BTW, yes, in HTML attributes, only the delimiter quote character ('/") and the escape character itself (&) need to be escaped. This is clearly defined in the HTML 5.2 standard. So there’s no need to painfully escape left and right angle brackets (</>) for these attributes when hand-typing HTML code. The code shown in the examples is browser-generated and so serves as a good example.

Placeholder

If a dropdown is used for the selection and no item is selected, the content of the dropdown button is empty. In this case, a placeholder text can be displayed with the placeholder option.

Width and wrapping

By default, the selectable and its dropdown button will have a width that fits the content. This can be avoided by setting the width of the original element to a fixed value. Here is an example with a dropdown button:

The dropdown button has a minimum width just like buttons. To reduce the width for very small buttons if there’s little space, add the narrow CSS class.

If the content of the selected item(s) does not fit in the dropdown button, it will be cropped. But it can also be set to wrap the content by adding the wrap CSS class.

Sortable selectable

Selectable and sortable lists can be combined. It is advisable to restrict the sortable movements to the list flow direction and within the list container.

Events

When an HTML <select> element is replaced, the visible element is not the original element that was in the document. To make it easier to use certain events with the UI element, they are forwarded to the original <select> element using the Frontfire.forwardUIEvents() method.

The change event is already managed by other actions and considered in both directions.

change

The change event has additional properties that indicate the reason of the change. This can be used for different event handling depending on how the change was made. The following event properties are added:

All additional event properties added in v2.1.0

focus

The original element’s focus() method is overwritten to focus the visible element instead.

Options

The following options are available:

Plugin properties

This plugin provides properties to access the selectable state.

Plugin methods

This plugin provides methods to control the selectable state.