Select

A “select” is a role="combobox" that does NOT allow editing its input. Currently, the only allowed combobox is one which has a “listbox” popup. Almost all elements except for the “anchored region” are in the light DOM for accessibility reasons. The select component has an internal search buffer which acts like a native <select> The currently hovered / focus <role-option> has [aria-current="true"] The currently selected <role-option> has [aria-selected="true"]

Single Select Examples

Setting a default selected value

Setting a default selected <role-option> is done by adding the selected attribute. This will also set defaultSelected so when the <role-select> resets, the option will reset as well.

Using a button as a trigger

A <button> can be passed in as the trigger for the select if you’d prefer. Make sure to set type="button".

Sometimes you want to use links in your select, rather than using click listeners to navigate a user, we can pass in href attribute to <role-option> to render an <a> tag under the hood.

Required Form Validation

Form validations for <role-select> currently only support the required attribute. Translations are handled for you by creating a hidden <select> with a required attribute.

Multiple select examples

Role Combobox supports “Multiple Select Comboboxes”. Just like with the single select selectes above, it supports 3 different types of autocomplete.

Comboboxes by default will use a space delimited value to submit. To enable a multi-select select, add the multiple attribute.

Changing the delimiter of the select

By default, the select has a , delimited value. If you want to change this, change the "delimiter" attribute.

Submitting all values instead of a single delimited string

By default, the select will submit a single string-delimited value. This may not always be desirable. To use FormData and submit multiple parameters based on the options selected, change the value-type attribute to "formdata"

Make sure to add a name attribute to the select to get the FormData to work properly.

API Reference

Imports

Script
HTML 
<!-- Auto registers as <role-select> -->
<script type="module" src="https://cdn.jsdelivr.net/npm/role-components/exports/select/select-register.js"></script>
CDN
HTML 
<script type="module">
  // Auto registers as <role-select>
  import "https://cdn.jsdelivr.net/npm/role-components/exports/select/select-register.js"

  // Manual Register
  import RoleSelect from "https://cdn.jsdelivr.net/npm/role-components/exports/select/select.js"
  RoleSelect.define()
  // => Registers as <role-select>
</script>
Bundler
JavaScript 
// Auto registers as <role-select>
import "role-components/exports/select/select-register.js"

// Manual Register
import RoleSelect "role-components/exports/select/select.js"
RoleSelect.define()
// => Registers as <role-select>

Attributes

Name Description Reflects Type Default
[Attribute + Property]
placement

The preferred placement of the popover. Note that the actual placement will vary as configured to keep the panel inside of the viewport.

 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'right' | 'right-start' | 'right-end' | 'left' | 'left-start' | 'left-end' "bottom"
[Attribute + Property]
distance

The distance in pixels from which to offset along the “main axis”. Usually its equivalent to offsetY

 number 6
[Attribute + Property]
expanded
-
 boolean false
[Attribute + Property]
multiple

Whether to allow multiple selections.

 boolean false
[Attribute]
wrap-selection

[Property]
wrapSelection
-
 boolean false
[Attribute + Property]
autocomplete

Any autocompletes of type "off", "inline", "list", or "both" will automatically make the triggerElement editable.

 '' | "off" | "inline" | "list" | "both" ''
[Attribute]
multiple-selection-type

[Property]
multipleSelectionType

If set to “automatic” (default), it will be one single text input with delimited values. If set to “manual”, you will only enter 1 option at a time, and then need to confirm selection, and then the input will clear, and then you will add another selection.

 "automatic" | "manual" "automatic"
[Attribute + Property]
editable

If true, the <input> element provided is not treated as readonly, and rather as an editable input. This can be omitted if you use any of the possible autocomplete attributes. Do not use this to check if the combobox is editable. instead, use this.isEditable to check if the triggerElement is editable.

 boolean false
[Attribute]
allow-custom-values

[Property]
allowCustomValues

When multiple-selection-type="manual", this allows users to see a custom <role-option> with the current value inside the combobox.

 boolean false
[Attribute]
show-empty-results

[Property]
showEmptyResults

If true, or show-empty-results attribute is present, it will show the “no-results-found” slot.

 boolean false
[Attribute + Property]
delimiter

Used for multiple select comboboxes that use value-type="string". The default is a comma.

 string ','
[Attribute + Property]
spacer

Used for multiple select comboboxes that use value-type="string". The default is a space.

 string " "
[Attribute]
filter-results

[Property]
filterResults

Whether or not to filter results based on what is typed into the combobox.

 boolean false
[Attribute]
search-buffer-delay

[Property]
searchBufferDelay

Delay before the search buffer returns to an empty string

 number 600
[Attribute]
value-type

[Property]
valueType

Used for multiple selects. You can either have a string, or submit as multiple parameters in FormData like a native <select>. The default is a “string”.

 "formdata" | "string" "string"
[Attribute]
value

[Property]
defaultValue
-
-
-
[Attribute]
current-placement

[Property]
currentPlacement

The currentPlacement property / current-placement attribute are where Floating UI actually positions the popup.

 this["placement"] | null
-
[Attribute + Property]
strategy

Determines how the popover is positioned. Because you native “popover” API uses a fixed strategy, we use it as the default.

 Strategy
-
[Attribute + Property]
skidding

The distance in pixels from which to offset along the “cross axis”. Usually its equivalent to offsetX.

 number
-
[Attribute + Property]
arrow

Attaches an arrow to the popover. The arrow’s size and color can be customized using the --arrow-size and --background-color custom properties. For additional customizations, you can also target the arrow using ::part(arrow) in your stylesheet.

 boolean
-
[Attribute]
arrow-placement

[Property]
arrowPlacement

The placement of the arrow. The default is anchor, which will align the arrow as close to the center of the anchor as possible, considering available space and arrow-padding. A value of start, end, or center will align the arrow to the start, end, or center of the popover instead.

 'start' | 'end' | 'center' | 'anchor'
-
[Attribute]
arrow-padding

[Property]
arrowPadding

The amount of padding between the arrow and the edges of the popover. If the popover has a border-radius, for example, this will prevent it from overflowing the corners.

 number
-
[Attribute + Property]
flip

When set, placement of the popover will flip to the opposite site to keep it in view. You can use flipFallbackPlacements to further configure how the fallback placement is determined.

 boolean
-
[Attribute]
flip-fallback-placements

[Property]
flipFallbackPlacements

If the preferred placement doesn’t fit, popover will be tested in these fallback placements until one fits. Must be a string of any number of placements separated by a space, e.g. “top bottom left”. If no placement fits, the flip fallback strategy will be used instead.

 string
-
[Attribute]
flip-fallback-strategy

[Property]
flipFallbackStrategy

When neither the preferred placement nor the fallback placements fit, this value will be used to determine whether the popover should be positioned using the best available fit based on available space or as it was initially preferred.

 'best-fit' | 'initial'
-
[Attribute]
flip-padding

[Property]
flipPadding

The amount of padding, in pixels, to exceed before the flip behavior will occur.

 number
-
[Attribute + Property]
shift

Moves the popover along the axis to keep it in view when clipped.

 boolean
-
[Attribute]
shift-padding

[Property]
shiftPadding

The amount of padding, in pixels, to exceed before the shift behavior will occur.

 number
-
[Attribute]
auto-size

[Property]
autoSize

When set, this will cause the popover to automatically resize itself to prevent it from overflowing.

 null | 'horizontal' | 'vertical' | 'both'
-
[Attribute + Property]
sync

Syncs the popover’s width or height to that of the anchor element.

 null | 'width' | 'height' | 'both'
-
[Attribute]
auto-size-padding

[Property]
autoSizePadding

The amount of padding, in pixels, to exceed before the auto-size behavior will occur.

 number
-
[Attribute]
hover-bridge

[Property]
hoverBridge

When a gap exists between the anchor and the popover element, this option will add a “hover bridge” that fills the gap using an invisible element. This makes listening for events such as mouseenter and mouseleave more sane because the pointer never technically leaves the element. The hover bridge will only be drawn when the popover is active.

 boolean
-

Events

Name Description
change
-
input
-

Functions

Name Description Parameters
focus()
-
 args
handleInput()
-
 event: InputEvent
splitValue()
-
 value: string
handleMultipleEditableInput()
-
 event: InputEvent, triggerElement: HTMLButtonElement | HTMLInputElement
__shouldSelectSuggestedOption()
-
 finalString: string, event: InputEvent
__findSuggestedOption()
-
 finalString: string, event: InputEvent, newSelectedOptions: typeof this.selectedOptions
__handleConfirmInput()
-
 event: InputEvent, triggerElement: HTMLButtonElement | HTMLInputElement
__handleAutomaticInput()
-
 event: InputEvent, triggerElement: HTMLButtonElement | HTMLInputElement
handleSingleEditableInput()
-
 event: InputEvent, triggerElement: typeof this.triggerElement
optionElementToOptionObject()
-
 el: RoleOption
handleOptionFocus()
-
 event: {target: null | RoleOption}
handleInputClick()
-
 e: Event
handleOutsideClick()
-
 e: Event
assignRandomId()

Users dont always provide ids on elements, and we need to make sure the id isn’t already taken.

 el: HTMLElement, id
updateListboxElement()

Adds proper attributes to the slotted listbox element
-
handleInputFocus()
-
 e: Event
updateTriggerElement()

Adds proper attributes to the slotted input element
-
renderSelectedOptions()
-
-
formResetCallback()
-
-
setCurrent()
-
 option: OptionObject
removeCurrent()
-
 option: OptionObject
findOptionElement()
-
 option: OptionObject
handleOptionClick()
-
 evt: PointerEvent
handleOptionHover()
-
 evt: Event
handleKeyUp()

Reset range when shiftKey goes up

 evt: KeyboardEvent
handleKeyDown()
-
 evt: KeyboardEvent
selectFromClosestSelectedToCurrent()

Finds the closest selected option prior to the current option
-
selectFromRangeStartToCurrent()
-
-
selectRange()

Selects all options in a range and deselects all options not in the range

 { from, to }, options: Range
selectFromStartToCurrent()
-
 startIndex: number
selectFromCurrentToEnd()
-
 endIndex: number
escapeRegexChars()

Escape characters for regex matching.

 str: string
stringToRegex()
-
 str: string
focusElementFromSearchBuffer()
-
-
select()
-
 option: OptionObject
deselect()
-
 option: OptionObject
selectAll()

Mark every element with [aria-selected=”true”]
-
deselectAll()

Mark every element with [aria-selected=”false”]

 updateOptions
toggleSelected()
-
 option: OptionObject
focusCurrent()
-
-
focusAt()
-
 index: number
focusNext()
-
-
focusPrevious()
-
-
focusFirst()
-
-
focusLast()
-
-
scrollOptionIntoView()
-
 selectedOption: OptionObject
scrollOptionElementIntoView()
-
 optionElement: HTMLElement
isSelected()
-
 option: OptionObject
updateOptions()
-
-
updateMultipleValue()

Updates formData / combobox.value

 force: boolean
updateCustomOption()
-
-
updateTriggerElementTextContentAndValue()
-
 str: string
debounce()
-
 callback: (...args: any[]) => any, options: { key: any, wait: number }
Previous Page Listbox Next Page Toolbar