GrSelect

<GrSelect
  v-model="value"
  v-model:search="query"
  :options="options"
  :loading="pending"
  filterable
  @search="fetchOptions"
/>

loading without v-model:search/@search used to be decorative: the typed text lived inside the component and did not come out — there was nothing to go to the server with. Now the query is available both ways: v-model:search for a controlled value and @search for a side effect.

While loading is on, there is no list in the DOM, so aria-controls is removed from the trigger — the reference does not hang into the void, and aria-busy stands in its place.

The direct children of role="listbox" are only options and groups: the role declares everything else an invalid child. The heading of a group lies inside its role="group" and gives it a name through aria-labelledby; loading and an empty result are taken out of the list into role="status" aria-live="polite" live regions — otherwise the states would change silently.

The options do not take the focus (tabindex="-1", mousedown suppressed): in a combobox it lives on the trigger or in the search field, and the active option is named by aria-activedescendant. A panel with a search field returns the focus to the trigger on closing — if it is still inside the panel.

The #empty and #loading slots replace both states.

dropdownMaxHeight is the ceiling of the list, not of the panel. The panel itself is limited by the space left up to the edge of the viewport: the layer reports the measurement in --gr-floating-available-height, and on a short screen it is the list that shrinks — the search field and the state rows stay in view, and there is one scrollbar. The mechanism is shared by the list panels of the package and is described in ../overlays.md.

virtual keeps in the DOM only the window around the viewport; its height is set by dropdownMaxHeight — or by the available space, if there is less of it. The mode is for optionsView="panel" only — a native <select> has no panel of its own at all.

<GrSelect v-model="city" :options="cities" options-view="panel" virtual />

The groups survive the window. If the panel is scrolled into the middle of a group, its heading is no longer in the markup — the role="group" wrapper is created all the same and takes its name through aria-label instead of aria-labelledby. Otherwise the options in the middle of a group would become direct children of the listbox and would lose the name of their set.

The set is counted by group rather than by list. With virtual the options carry aria-setsize/aria-posinset, and for an option inside a group that is the size of its group — that is what ARIA requires. Options outside groups together with the “Add …” button form the set at the level of the listbox. In the ordinary mode the attributes are absent: there the set is visible in the DOM.

It does not combine with view="link". In that look the options carry w-max, that is, the width of the panel equals the width of the widest rendered option — with virtualisation it would jump on every scroll. The package reports both incompatible combinations with a dev warning. How the primitive works — virtual-list.md.

aria-activedescendant works only on the element that holds the focus. With filterable/allowCustomValue the focus goes into the search field inside the panel — the link with the active option lives there as well, and the field declares itself role="combobox". Without a search field everything stays on the trigger.

When the panel opens, the selected option becomes the active one, and the list is scrolled to it at once — with virtual too: the window settles around it, and aria-activedescendant always points to a rendered element. The arrows keep the active option inside the window.

<GrSelect v-model="values" multiple tags :max-tag-count="3" :options="options" />

The chips live beside the combobox button rather than inside it: role="combobox" declares its descendants presentational, and a cross inside was unreachable from the keyboard (axe: nested-interactive). Now those are real buttons in the tab order.

maxTagCount folds the tail into a “+N” — without it a long selection turned into a sheet of chips.

The field grows together with the rows of chips. In a narrow column the chips wrap, and the field becomes taller — never lower than the ordinary control row of its size; the border and the focus ring go round all the rows. The chevron and the clear button sit at the vertical centre. Previously the field kept the height of a single row, and the second row hung below the border on top of whatever came next.

The colour of a tag is also set on an option: the tone and dark of the option itself override the general tagTone/tagDark. That is needed more often than it seems — labels, categories and statuses usually arrive with a colour of their own — and without such a possibility the consumer went off to draw the selection in the #value slot and lost exactly what tags is taken for: chips outside role="combobox", removal with a cross, folding into a “+N” and the keyboard.

const options = [
  { value: 'bug', label: 'Bug', tone: 'danger' },
  { value: 'idea', label: 'Idea', tone: 'success', dark: true },
]

The panel is controllable through v-model:open (the contract of the panel overlays of the package, as in GrPopover): without the open prop the select runs itself, with it the parent owns the state. The name prop enables participation in a native form: in the native mode the name goes onto the <select> itself, and in the panel mode the values are serialised with hidden inputs (the key is valueKey/keyOf, one per value with multiple).

The default slot accepts <option> and <optgroup> of your own — for example, an unavailable hint as the first row. Their selection is set by the component from v-model, as for the options from options: there is no need to write a :selected of your own, and the server renders the option already selected.

<template>
  <GrSelect v-model="country" name="country">
    <option value="" disabled>
      Choose a country
    </option>
    <optgroup label="Next working day">
      <option value="ie">
        Ireland
      </option>
    </optgroup>
  </GrSelect>
</template>

Previously the options from the slot got nothing: with country = '' the browser showed the first available option, and a programmatic change of the model never reached the screen.

A single native select always shows an empty model (undefined, null, '') as empty. With clearable the clear option shows it. Without it the component puts first a hint option <option value="" disabled hidden selected> with the text of placeholder, and without that — the translated “Select…” (gr.select.placeholder). Without such an option the browser picks the first one itself: the field would show “Germany” with an empty value, and select.value would go into the form past the model.

While the field shows the hint or the clear option, the <select> carries data-gr-select-empty, and its text is in the hint colour (--gr-muted-fg), like ::placeholder of GrInput: otherwise the hint reads as a chosen value. The options of the opened list get the normal colour back, disabled ones the browser’s. The colours are set by an inline style rather than utilities: a rule with the same body would merge with a shared one and shift the order of rules for the neighbours.

The hint cannot be picked back (disabled) and is not in the opened list (hidden): without clearable there is no way to return to “nothing” — that is intended for a required field. As soon as a value is chosen, the hint is gone. If options has an option with an empty value, it is itself the “nothing selected”, and the hint is not added; your own empty <option> in the slot overrides it in the same way.

<GrSelect v-model="owner" :options="ownerOptions" value-key="id" />

The value of an option may be an object — then valueKey with the name of the identifier field is mandatory. Through it the component builds the key by which it compares the values and puts them into the DOM: === would mean comparing references, and the model usually arrives from the outside as a separate copy — with the same id but a different object, and it would match none of the options. Without valueKey object values give a warning in a dev build.

The object itself goes out, not a string from the DOM. allowCustomValue does not work with object values by nature: the user types text.

state (default | success | warning | danger) sets the hue of the border, invalid forces the red one and announces aria-invalid — an error overrides any other highlighting. In view="link" there is no border, and the state is not applied there.

readonly shows the value but does not open the panel and does not change the selection; disabled dims the whole control. The clear button does not hide the chevron: a field with a selected value has to look like a dropdown list.

The heading of a group is linked to the options through aria-describedby — that way the group is heard without turning a flat list into a tree.

The slots are available only with optionsView="panel" — markup cannot be put inside a native <select> (in dev the console will warn about that). They put an icon, a unit or a label into the shell; the width is bounded by six props (prefixMinWidth/prefixMaxWidth/prefixFixed and the same for the suffix). The shared contract of the controls — form-controls.md.

focus() and blur() through a ref on the component — in the native mode they address the <select>, in the panel mode the trigger button.