<bmx-select>

<div class="row">
  <bmx-select id="ex-select-country" label="Country" placeholder="Choose a country" description="Type a letter with the list closed and it jumps straight there, as a native select does."></bmx-select>
</div>
<div class="row">
  <bmx-select id="ex-select-team" label="Assign to" multiple="true" clearable="true" max-tags="2" description="Several choices, collapsed into a count once there are more than two."></bmx-select>
</div>
<div class="row">
  <bmx-select id="ex-select-big" label="Reference" placeholder="One of five thousand" description="Windowed: about twenty rows exist at a time, whatever the scrollbar says."></bmx-select>
</div>
<script type="module">
  // `options` is a property rather than an attribute, because it is an array.
  // Waiting for the element to be defined means the assignment cannot land on
  // a plain <bmx-select> that has not upgraded yet.
  await customElements.whenDefined('bmx-select');

  document.getElementById('ex-select-country').options = [
    { value: 'gb', label: 'United Kingdom', group: 'Europe' },
    { value: 'ie', label: 'Ireland', group: 'Europe' },
    { value: 'de', label: 'Germany', group: 'Europe' },
    { value: 'us', label: 'United States', group: 'Americas' },
    { value: 'ca', label: 'Canada', group: 'Americas' },
    { value: 'br', label: 'Brazil', group: 'Americas', disabled: true },
  ];

  document.getElementById('ex-select-team').options = [
    { value: 'ana', label: 'Ana Silva', description: 'Platform' },
    { value: 'ben', label: 'Ben Okafor', description: 'Platform' },
    { value: 'cara', label: 'Cara Ellis', description: 'Design' },
    { value: 'dev', label: 'Dev Patel', description: 'Design' },
  ];

  document.getElementById('ex-select-big').options = Array.from({ length: 5000 }, (_, index) => ({
    value: `REF-${index}`,
    label: `REF-${String(index).padStart(5, '0')}`,
  }));
</script>

WHAT IT IS NOT

It is not searchable, and that is a decision rather than an omission. A control the user can type into is a combobox: its trigger is a text field, its keyboard is filtering rather than typeahead, and its ARIA is a different shape. bmx-combobox is that component, and a combobox that refuses values outside its list is the "searchable select" this one is sometimes asked to be. Folding both into one tag behind a flag would mean a property that silently changes an element's role, which is the thing this library keeps declining to do.

What it does have is typeahead, which is what a native <select> has: type a few characters and the active option jumps, and repeat one character to cycle through everything starting with it. That second half is in src/core/listbox.ts with the rest of the arithmetic.

WHY OPTIONS ARE DATA

options is an array, because a virtualised list has to own its data - a thousand slotted elements are the exact cost windowing exists to avoid, paid before the component starts. <bmx-option> children are supported as a declarative front door for hand-written markup, and are read once into the same array. A non-empty options property wins; the two are never merged, because two sources of truth for a list is how a select ends up showing something the application does not think is there.

VIRTUALISATION, AND WHEN IT TURNS ON

Below virtualThreshold rows every row is rendered and each is whatever height its content needs. Above it the list is windowed, which requires rows of a uniform height - so a long list gets one line per option whatever the label. Short lists, which is nearly all of them, pay nothing for any of this and are free to have two-line options.

The height is measured off a rendered row rather than read from the custom property that sets it. getComputedStyle hands a custom property back as the token that was written - 2.25rem, not 36px - and a virtualiser told its rows are two pixels tall renders the entire list, which is exactly what happened the first time this was built.

The keyboard has to be windowing-aware too. scrollIntoView needs an element, and the row an arrow key just moved to may not be rendered - so the scroll position is computed from the row offsets instead, in scrollOffsetFor.

ACCESSIBILITY

The APG select-only combobox pattern: role="combobox" on the trigger with aria-expanded and aria-controls, a role="listbox" surface, and aria-activedescendant moving the visual focus while real focus stays on the trigger. Arrow keys move the active option and Enter commits it - not the native <select>'s "arrowing changes the value", which cannot be expressed in this pattern and is not what a screen reader user expects from something announcing itself as a combobox.

Groups survive windowing: each run of consecutive same-group rows in the window is wrapped in a role="group", and a window that begins in the middle of a group is still wrapped in it, using the heading it scrolled past. Every option carries aria-setsize and aria-posinset counted over the whole list, because the browser can only count what is rendered.