Skip to main content
Logo USWDS + Tailwind

Combo box

A combo box helps users select an item from a large list of options.

This component requires the following JavaScript plugins:

Example

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
Twig 
<div x-combobox class="max-w-lg">
	<label x-combobox:label for="combobox" class="block">Select a fruit</label>


	<select id="combobox" x-combobox:values>
		{% for combobox in comboboxes %}
			<option value="{{- combobox.value -}}">{{- combobox.label -}}</option>
		{% endfor %}
	</select>


	<template x-if="$combobox.isLoaded">
		<div class="relative mt-2">
			<div class="flex w-full">
				<input x-combobox:input class="pr-10 p-2 bg-white w-full h-10 border border-gray-60 focus:outline focus:outline-offset-0 focus:outline-4 focus:outline-blue-40v data-[invalid]:ring-4 data-[invalid]:ring-red-60v data-[invalid]:border-transparent data-[invalid]:outline-offset-4">
				<div class="absolute z-10 inset-y-0 right-0 flex">
					<button x-combobox:clear class="h-full px-1 flex items-center focus:outline focus:-outline-offset-4 focus:outline-4 focus:outline-blue-40v/60 bg-transparent">
						<div class="icon-[material-symbols--close] size-6 align-middle text-gray-50"></div>
					</button>
					<button x-combobox:toggle class="h-full px-1 flex items-center focus:outline focus:-outline-offset-4 focus:outline-4 focus:outline-blue-40v/60 bg-transparent">
						<div class="icon-[material-symbols--expand-more] size-8 align-middle text-gray-50"></div>
					</button>
				</div>
			</div>
			<ul x-combobox:list class="absolute border border-t-0 border-gray-60 bg-white max-h-52 overflow-y-scroll w-full z-10">
				<template x-for="option in $combobox.allOptions" :key="option.value">
					<li x-combobox:item class="p-2 cursor-pointer aria-selected:bg-blue-60v aria-selected:text-white data-[active]:outline data-[active]:outline-4 data-[active]:outline-blue-40v data-[active]:-outline-offset-4" x-text="option.label"></li>
				</template>
				<template x-if="$combobox.noResults">
					<li class="p-2 cursor-not-allowed">
						No results found
					</li>
				</template>
			</ul>
		</div>
	</template>
</div>

Component API

Root

  • x-combobox

    Custom Alpine directive that marks the Combobox Root.

Label

  • x-combobox:label

    Custom Alpine directive that marks the Combobox Label.

  • id

    Type: string

    Used to link the Combobox Label to the Combobox List via aria-labelledby.

  • for

    Type: string

    Links the Combobox Label to the Combobox Input.

    By default, this value should match the id on the select element. When Javascript loads, this value will be updated to match the id of the Combobox Input.

Values

  • x-combobox:values

    Custom Alpine directive that marks the Combobox Values.

  • hidden

    Type: boolean
    Default: true

    Attribute is applied when JavaScript is loaded to hide the initial <select> element.

    Automatically handled with JavaScript.

Input

  • x-combobox:input

    Custom Alpine directive that marks the Combobox Input.

  • id

    Type: string

    Used to link the Combobox Input to the Combobox Label via for.

    Automatically handled with JavaScript.

  • role

    Value: 'combobox'

    Automatically handled with JavaScript.

  • aria-expanded

    Type: boolean
    Default: false

    Accessibility attribute that communicates whether the Combobox List is expanded or collapsed.

    Automatically handled with JavaScript.

  • aria-activedescendant

    Type: string

    Accessibility attribute that communicates which, if any, Combobox Item is currently focused.

    Automatically handled with JavaScript.

  • aria-controls

    Type: string

    Accessibility attribute that communicates that the Combobox Input controls the state of the Combobox List and visibility of Combobox Items.

    Automatically handled with JavaScript.

  • aria-owns

    Type: string

    Accessibility attribute establishes the contextual relationship between the Combobox Input and the Combobox List

    Automatically handled with JavaScript.

List

  • x-combobox:list

    Custom Alpine directive that marks the Combobox List.

  • role

    Type: string
    Value: 'listbox'

    Automatically handled with JavaScript.

  • aria-labelledby

    Type: string

    Accessibility attribute that links the Combobox List to the Combobox Label via id.

    Automatically handled with JavaScript.

  • tabindex

    Type: number
    Value: -1

    Prevents users from tabbing to this element.

    Automatically handled with JavaScript.

Item

  • x-combobox:item

    Custom Alpine directive that marks the Combobox Item.

  • id

    Type: string

    Used to link the Combobox Item to the Combobox Input via aria-activedescendant.

    Automatically handled with JavaScript.

  • role

    Value: 'option'

    Automatically handled with JavaScript.

  • aria-selected

    Type: boolean
    Default: false

    Accessibility attribute the communicates the selected state of the Combobox Item.

    Automatically handled with JavaScript.

  • data-active

    Type: boolean
    Default: false

    Attribute used to style the the Combobox Item element when hovered or focused. Defaults to false, set to true when an item is hovers or focused.

    Automatically handled with JavaScript.

  • tabindex

    Type: number
    Default: -1

    Prevents users from tabbing to this element. Defaults to -1, set to 0 when item it hovered or focused.

    Automatically handled with JavaScript.

Toggle Button

  • x-combobox:toggle

    Custom Alpine directive that marks the Combobox Toggle Button.

  • aria-label

    Type: string

    Automatically handled with JavaScript.

  • tabindex

    Type: number
    Value: -1

    Prevents users from tabbing to this element.

    Automatically handled with JavaScript.

Clear Button

  • x-combobox:clear

    Custom Alpine directive that marks the Combobox Clear Button.

  • aria-label

    Type: string

    Automatically handled with JavaScript.

  • tabindex

    Type: number
    Value: -1

    Prevents users from tabbing to this element.

    Automatically handled with JavaScript.

Keyboard Interactions

  • Down Arrow

    When focus is on an Combobox Input, opens the Combobox List and moves focus on the currently selected that Combobox Item. Otherwise, moves focus to the first Combobox Item.

    When focus is on an Combobox Item, moves focus to the previous focusable element.

    When focus is on the first Combobox Item in a Combobox List, moves focus to the Combobox Input.

  • Up Arrow

    When focus is on an Combobox Input, opens the Combobox List and moves focus on the currently selected that Combobox Item. Otherwise, moves to the last Combobox Item.

    When focus is on an Combobox Item, moves focus to the next focusable element.

    When focus is on the last Combobox Item in a Combobox List, focus moves to the Combobox Input.

  • Enter

    When focus is on an Combobox Item, selects the current value and sets the cursor at the end of the selected value in the Combobox Input.

  • Escape

    When the Combobox List is open, closes the Combobox List and moves focus to the Combobox Input.

Progressive Enhancement

Because this component heavily relies on Javascript, in environments where Javascript isn’t present or hasn’t yet loaded, this component falls back to the native <select> element. When Javascript is loaded, the <select> element will be hidden and all options will be passed to the Combobox component.

This ensures that users will always be able to interact with a functional component regardless of their connectivity or browser settings.