Intro
Combobox er en komponent som kombinerer tekstfelt og nedtrekksliste. Den lar brukeren skrive direkte i tekstfeltet eller velge fra en liste med alternativer i nedtrekkslista. Vanlige brukstilfeller er når brukeren skal velge blant mange predefinerte alternativer, ikke kjenner alternativenes stavemåte eller ikke vet nøyaktig hvilke alternativer som finnes.
Egnet til:
- Velge blant en lang liste av alternativer
- Oppgi verdier på et standardisert format, som navn på land
- Velge én eller velge flere verdier
- Søke i store datasett
Uegnet til:
- Færre enn 7 alternativer (bruk Radio-knapper eller Checkbox)
Eksempler
Ved Single Select velger brukeren ett valg fra listen. Med autocomplete foreslås et valg fra listen som matcher det brukeren skriver.
Ved Single Select velger brukeren kun ett valg fra nedtrekkslisten.
Ved Single Select velger brukeren kun ett valg fra nedtrekkslisten.
Du kan overstyre blant annet value, selectedOptions, filteredOptions.
Ved Multi Select kan brukeren velge flere valg fra nedtrekkslisten.
Ved Multi Select kan brukeren velge flere valg fra listen.
Retningslinjer
Legg til alternativer
Combobox kan settes opp til å ta imot nye alternativer som ikke finnes i nedtrekslista. Det er smart å bruke denne muligheten når du vil vise noen gode alternativer, men samtidig gi brukerne muligheten til å legge til egne alternativer.
Vise valg eksternt
Combobox har muligheten til å vise valgte alternativer utenfor komponentens tekstfelt. Det er ofte brukt i løsninger med flere filter som viser hva som er valgt over en resultatoversikt. Det er også en mulig løsning for alternativer med tilknyttet data/metadata som trenger større plass for å vise alt innholdet.
Listeinnhold
Hold teksten i alternativene så kort at de passer i bredden til nedtrekslista. Om teksten blir lang vil den gå over flere linjer. Lange tekster gjør alternativene vanskelige å lese.
Antall alternativer
Combobox fungerer best med større datasett hvor brukerne trenger en søke/filter-mekanisme for å ta valg. Om du har mindre enn 7 alternativer å velge mellom, så er det bedre å bruke Radio eller Checkbox.
Tilgjengelighet
Komponenten følger i stor grad WAI-ARIA Practices Guide (APG) sin implementasjon av combobox-mønsteret.
Hoveddelene av komponenten er et inputfelt og nedtrekklisten. Input-feltet har rollen combobox, og den kobles til nedtrekkslisten med aria-autocomplete="list"
og aria-controls="<liste-id>"
. Dette kommuniserer for skjermleserbrukere at det er mulig å bruke piltaster for å bla mellom valgene i listen med piltaster fra input-feltet.
Fokushåndtering
Det er hovedsakelig kun inputtfeltet som får fokus. Det er for å redusere antall tab-stopp for komponenten, slik at den oppleves likt som en native select
. Deretter styres et virtuelt fokus når brukeren blar i nedtrekkslisten. Det kommuniseres til skjermleser ved hjelp av aria-activedecendant
og markeres visuelt med endring av bakgrunnsfarge og en tykk strek på venstre side.
Når man bruker Multi Select-versjonen av Combobox kan man også flytte fokuset til de allerede valgte alternativene sine, gitt at man har noen.
Input-type
Vi har valgt å bruke type="text"
på input-feltet. For noen tilfeller ville kanskje type="search" virke mer logisk, da brukeren funksjonelt bruker komponenten for å søke i verdier. Men gjennom brukertesting har denne typen fungert dårligere med skjermleser/leselist, så vi gikk derfor tilbake til type="text"
.
Autocomplete
I Single Select-versjonen autofullfører vi til det første treffet fra listen. Vi bruker setSelectionRange
for å velge teksten vi har lagt til, slik at neste tastetrykk fortsetter å skrive på det originale ordet. Opplesingen varierer litt med forskjellige skjermlesere, og brukertesting viste at det kunne være vanskelig å få med seg det hele ordet som ble autofullført. Derfor har vi lagt til aria-describedby
, som peker på det første ordet i nedtrekkslisten. Dette er det samme ordet vi bruker for autofullfør. Dermed blir hele ordet lest opp når et nytt ord autofullføres, men ikke for hvert enkelt tastetrykk.
Tastaturinteraksjon
Kommando | Interaksjon |
---|---|
Tab | Navigerer fremover i allerede valgte alternativer |
Shift+Tab | Navigerer bakover i allerede valgte alternativer |
ArrowUp | Navigerer til starten av teksten i input-feltet eller til forrige valg i nedtrekkslisten |
ArrowDown | Navigerer til slutten av teksten i input-feltet eller til neste valg i nedtrekkslisten |
Enter | Bekrefter autocomplete eller valget med virtuelt fokus i nedtrekkslisten |
Home | Navigerer til starten av input-feltet |
End | Navigerer til siste valg i nedtrekkslisten |
Props
Props
- value? string
- Set this to override the value of the input field. This converts the input to a controlled input, so you have to use onChange to update the value.
- disabled? boolean
- Disables element @note Avoid using if possible for accessibility purposes
- readOnly? boolean
- Read only-state
- className? string
- id? string
- Override internal id
- label ReactNode
- Combobox label
- allowNewValues? boolean
- If enabled, adds an option to add the value of the input as an option whenever there are no options matching the value.
- clearButton? boolean
- If "true" adds a button to clear the value in the input field
- clearButtonLabel?string
- Custom name for the clear button. Requires "clearButton" to be "true".
- filteredOptions? string[]
- A list of options to display in the dropdown list. If provided, this overrides the internal search logic in the component. Useful for e.g. searching on a server or when overriding the search algorithm to search for synonyms or similar.
- hideLabel? boolean
- Optionally hide the label visually. Not recommended, but can be considered for e.g. search fields in the top menu.
- inputClassName? string
- Custom class name for the input field. If used for styling, please consider using tokens instead.
- isListOpen? boolean
- Controlled open/closed state for the dropdown list
- isLoading? boolean
- Set to "true" when doing an async search and waiting for new filteredOptions. Will show a spinner in the dropdown and announce to screen readers that it is loading.
- isMultiSelect? boolean
- Set to "true" to allow multiple selections This will display selected values as a list of Chips in front of the input field, instead of a selection replacing the value of the input.
- onClear? ((event: PointerEvent<Element> | KeyboardEvent<Element>) => void)
- Callback function triggered whenever the input field is cleared @param event @returns
- onToggleSelected? ((option: string, isSelected: boolean, isCustomOption: boolean) => void)
- Callback function triggered whenever an option is selected or de-selected @param option @param isSelected - Whether the option has been selected or unselected @param isCustomOption - Whether the option comes from user input, instead of from the list @returns
- selectedOptions? string[]
- List of selected options. Use this prop when controlling the selected state outside for the component, e.g. for a filter, where options can be toggled elsewhere/programmatically.
- shouldAutocomplete?boolean
- Set to "true" to enable inline autocomplete.
- shouldShowSelectedOptions?boolean
- When set to "true" displays selected options as Chips before the input field
- toggleListButton?boolean
- When set to "true" displays the toggle button for opening/closing the dropdown list
- toggleListButtonLabel?string
- Custom name for the toggle list-button. Requires "toggleListButton" to be "true".
- error? ReactNode
- Error message for element
- errorId? string
- Override internal errorId
- description? ReactNode
- Adds a description to extend labling of a field
- ref? Ref<HTMLInputElement>
- Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). @see https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom
- extends HTMLInputElement