Combobox

Combobox lets users filter and select from a list of options by typing. It combines a text input with a dropdown menu.

Comboboxes combine a text input with a dropdown menu, allowing users to search and filter through options. Unlike selects, comboboxes are searchable by default, making them ideal for larger lists where users need to quickly find specific items.

<ahi-combobox label="Select a country" placeholder="Type to search...">
  <ahi-combobox-option value="us">United States</ahi-combobox-option>
  <ahi-combobox-option value="ca">Canada</ahi-combobox-option>
  <ahi-combobox-option value="mx">Mexico</ahi-combobox-option>
  <ahi-combobox-option value="uk">United Kingdom</ahi-combobox-option>
  <ahi-combobox-option value="de">Germany</ahi-combobox-option>
  <ahi-combobox-option value="fr">France</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Examples

Help text

Add descriptive help text to a combobox with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

<ahi-combobox
  label="Select your state"
  placeholder="Type to search..."
  help-text="Start typing to filter the list of states"
>
  <ahi-combobox-option value="al">Alabama</ahi-combobox-option>
  <ahi-combobox-option value="ak">Alaska</ahi-combobox-option>
  <ahi-combobox-option value="az">Arizona</ahi-combobox-option>
  <ahi-combobox-option value="ar">Arkansas</ahi-combobox-option>
  <ahi-combobox-option value="ca">California</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Clearable

Use the clearable attribute to add a clear button that lets users quickly remove the selected value.

<ahi-combobox label="Select one" placeholder="Type to search..." clearable>
  <ahi-combobox-option value="option-1">Option 1</ahi-combobox-option>
  <ahi-combobox-option value="option-2">Option 2</ahi-combobox-option>
  <ahi-combobox-option value="option-3">Option 3</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Disabled

Use the disabled attribute to disable a combobox.

<ahi-combobox label="Select one" placeholder="Type to search..." disabled value="option-1">
  <ahi-combobox-option value="option-1">Option 1</ahi-combobox-option>
  <ahi-combobox-option value="option-2">Option 2</ahi-combobox-option>
  <ahi-combobox-option value="option-3">Option 3</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Multiple selection

To allow multiple options to be selected, use the multiple attribute. Selected options are displayed as tags inside the input.

<ahi-combobox label="Select multiple" placeholder="Type to search..." multiple clearable>
  <ahi-combobox-option value="option-1">Option 1</ahi-combobox-option>
  <ahi-combobox-option value="option-2">Option 2</ahi-combobox-option>
  <ahi-combobox-option value="option-3">Option 3</ahi-combobox-option>
  <ahi-combobox-option value="option-4">Option 4</ahi-combobox-option>
  <ahi-combobox-option value="option-5">Option 5</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Setting initial values

Use the value attribute to set the initial selection.

When using multiple, the value property is an array of the selected options’ values, and option values may contain any characters — including spaces. Only the value attribute is space-delimited (HTML attributes can’t express arrays), so options whose values contain spaces can’t be preselected from markup; assign an array to the value property instead.

<ahi-combobox label="Select one" value="option-1 option-2" multiple clearable>
  <ahi-combobox-option value="option-1">Option 1</ahi-combobox-option>
  <ahi-combobox-option value="option-2">Option 2</ahi-combobox-option>
  <ahi-combobox-option value="option-3">Option 3</ahi-combobox-option>
  <ahi-combobox-option value="option-4">Option 4</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Grouping options

Use <ahi-divider> and <ahi-menu-label> to group options visually.

<ahi-combobox label="Select a fruit" placeholder="Type to search...">
  <ahi-menu-label>Citrus</ahi-menu-label>
  <ahi-combobox-option value="orange">Orange</ahi-combobox-option>
  <ahi-combobox-option value="lemon">Lemon</ahi-combobox-option>
  <ahi-combobox-option value="lime">Lime</ahi-combobox-option>
  <ahi-divider></ahi-divider>
  <ahi-menu-label>Berries</ahi-menu-label>
  <ahi-combobox-option value="strawberry">Strawberry</ahi-combobox-option>
  <ahi-combobox-option value="blueberry">Blueberry</ahi-combobox-option>
  <ahi-combobox-option value="raspberry">Raspberry</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Placement

The preferred placement of the combobox’s dropdown can be set with the placement attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are top and bottom.

<ahi-combobox label="Select one" placeholder="Type to search..." placement="top">
  <ahi-combobox-option value="option-1">Option 1</ahi-combobox-option>
  <ahi-combobox-option value="option-2">Option 2</ahi-combobox-option>
  <ahi-combobox-option value="option-3">Option 3</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Prefix & suffix

Use the prefix and suffix slots to add presentational icons and text. Avoid slotting in interactive elements, such as buttons, links, etc.

<ahi-combobox label="Select one" placeholder="Type to search..." clearable>
  <ahi-icon name="search" slot="prefix"></ahi-icon>
  <ahi-badge slot="suffix">New</ahi-badge>
  <ahi-combobox-option value="option-1">Option 1</ahi-combobox-option>
  <ahi-combobox-option value="option-2">Option 2</ahi-combobox-option>
  <ahi-combobox-option value="option-3">Option 3</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Async/lazy loading

The combobox supports supplying options dynamically based on user input. Use the lazy attribute and listen for the ahi-search-change event. When lazy is enabled the combobox’s own client-side filtering is switched off and the consumer is responsible for filtering — from a server call, or from a list it already holds in memory. Both are supported; the in-memory case is covered below.

Reach for lazy whenever the full list is large, whether or not you have a search endpoint. Non-lazy filtering works by setting hidden on option elements, so every option has to be in the DOM for it to work — lazy is the only way to keep the DOM small.

<ahi-combobox id="async-demo" label="Search users" placeholder="Type to search..." lazy>
</ahi-combobox>

<script type="module">
  const combobox = document.getElementById('async-demo');
  let searchController = null;

  // Simulated API call with server-side filtering
  async function searchUsers(query, signal) {
    // Simulate network delay
    await new Promise((resolve, reject) => {
      const timeout = setTimeout(resolve, 800);
      signal?.addEventListener('abort', () => {
        clearTimeout(timeout);
        reject(new DOMException('Aborted', 'AbortError'));
      });
    });

    const allUsers = [
      { id: '1', name: 'Alice Johnson' },
      { id: '2', name: 'Bob Smith' },
      { id: '3', name: 'Charlie Brown' },
      { id: '4', name: 'Diana Prince' },
      { id: '5', name: 'Eve Anderson' }
    ];

    // Server performs the filtering
    if (!query) return allUsers;
    return allUsers.filter(user =>
      user.name.toLowerCase().includes(query.toLowerCase())
    );
  }

  combobox.addEventListener('ahi-search-change', async (e) => {
    const query = e.detail.query;

    // Cancel any pending search
    if (searchController) {
      searchController.abort();
    }
    searchController = new AbortController();

    // Show loading spinner (replaces expand icon)
    combobox.loading = true;

    // Clear existing options immediately
    combobox.innerHTML = '';

    try {
      // Fetch filtered results from server
      const users = await searchUsers(query, searchController.signal);

      // Add new options
      users.forEach(user => {
        const option = document.createElement('ahi-combobox-option');
        option.value = user.id;
        option.textContent = user.name;
        combobox.appendChild(option);
      });

      // Hide loading spinner
      combobox.loading = false;
    } catch (err) {
      // Ignore abort errors (new search started)
      if (err.name !== 'AbortError') {
        combobox.loading = false;
        throw err;
      }
    }
  });
</script>

        
  
        
      

Filtering an in-memory list

There is no requirement that lazy talk to a server. When the full list is already on the client — and is too large to put in the DOM all at once — filter it in memory and render a capped slice. This is the same pattern as above without the network, so there is no spinner and no request to cancel.

Note the total-results attribute: it tells the combobox the true size of the match set so it can say what it is not showing. Without it a capped list looks complete. See Truncated results.

<ahi-combobox id="in-memory-demo" label="Rendering provider" placeholder="Search providers" lazy load-more>
</ahi-combobox>

<script type="module">
  const combobox = document.getElementById('in-memory-demo');
  const PAGE_SIZE = 10;

  // The whole list, already on the client. Stand-in for a few thousand practitioners.
  const providers = Array.from({ length: 240 }, (_, i) => ({
    id: String(i + 1),
    name: `Provider ${String(i + 1).padStart(3, '0')}, MD`
  }));

  let rendered = PAGE_SIZE;

  function matches(query) {
    if (!query) return providers;
    const term = query.toLowerCase();
    return providers.filter(p => p.name.toLowerCase().includes(term));
  }

  function render(query) {
    const found = matches(query);

    // Tell the combobox the real total, then render only the slice.
    combobox.totalResults = found.length;
    combobox.innerHTML = '';

    found.slice(0, rendered).forEach(provider => {
      const option = document.createElement('ahi-combobox-option');
      option.value = provider.id;
      option.textContent = provider.name;
      combobox.appendChild(option);
    });
  }

  combobox.addEventListener('ahi-search-change', event => {
    // A new query starts a new slice
    rendered = PAGE_SIZE;
    render(event.detail.query);
  });

  combobox.addEventListener('ahi-load-more', event => {
    rendered = event.detail.rendered + PAGE_SIZE;
    render(combobox.searchQuery);
  });

  render('');
</script>

        
  
        
      

Truncated results

In lazy mode the combobox only ever sees the slice you rendered, so it cannot know how many options actually matched. Set total-results and it will state what it is showing at the foot of the listbox — Showing 10 of 240 — resolving to Showing all 7 matches once the slice is the whole set.

That covers the first half of the problem: the list no longer presents a capped slice as if it were complete. For the second half — letting someone browse to an option without already knowing its name — add load-more and handle ahi-load-more:

• load-more renders a Show more control in the footer. It joins the arrow-key cycle after the last option, so a keyboard user reaches it by continuing to press Down. Activating it moves focus to the first newly-added option.
• load-more-count sets the slice size used in the label, so it reads Show 10 more rather than Show more.
• ahi-load-more fires with { rendered, total }. The consumer appends and re-renders; the combobox never fetches anything itself.

Prefer load-more to a scroll-driven reveal. ahi-listbox-scroll-end exists for consumers who want the latter, but there is deliberately no built-in scroll UI: it is the most fluid option with a mouse and the worst by any other means — nothing to tab to and nothing for a screen reader to act on.

If the footer’s own wording does not suit, fill the listbox-footer slot and render your own. Doing so replaces the generated footer entirely, so include the count yourself — and remember an aria-live region if the count changes, or the update is silent to a screen reader.

<ahi-combobox label="Rendering provider" placeholder="Search providers" lazy total-results="2736" load-more load-more-count="50" open>
  <ahi-combobox-option value="1">Abbott, Marcus R., MD</ahi-combobox-option>
  <ahi-combobox-option value="2">Acevedo, Lina P., NP</ahi-combobox-option>
  <ahi-combobox-option value="3">Allen, Thomas W., DO</ahi-combobox-option>
  <ahi-combobox-option value="4">Adams, Priya N., MD</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Non-searchable mode

Set searchable to false to make the combobox behave like a regular select (readonly input). This is useful when you want the combobox appearance but don’t need search functionality.

<ahi-combobox label="Select one" placeholder="Select an option" searchable="false">
  <ahi-combobox-option value="option-1">Option 1</ahi-combobox-option>
  <ahi-combobox-option value="option-2">Option 2</ahi-combobox-option>
  <ahi-combobox-option value="option-3">Option 3</ahi-combobox-option>
</ahi-combobox>

        
  
        
      

Combobox vs Select

While both components allow users to choose from a list of options, there are key differences:

Use <ahi-combobox> when:

• You have a large list of options (10+ items)
• Users need to search/filter options
• You need async/lazy loading of options
• You want a more modern, searchable interface

Use <ahi-select> when:

• You have a small list of options (< 10 items)
• Options don’t need to be searchable
• You want the native select behavior
• You prefer a simpler, more traditional dropdown

Accessibility

The combobox follows the ARIA Combobox Pattern and includes:

• Proper ARIA roles (combobox, listbox, option)
• Keyboard navigation (Arrow keys, Home, End, Enter, Escape)
• Screen reader announcements for selection changes
• Focus management
• Live region updates for search results

Keyboard shortcuts

• Enter - Opens the dropdown or selects the current option
• Escape - Closes the dropdown
• Arrow Up/Down - Navigate through options
• Home/End - Jump to first/last option
• Type - Search/filter options (when searchable)
• Tab - Moves focus to the next focusable element

Text assistance and mobile keyboards

The search field accepts the same assistance and keyboard attributes as <ahi-input>: autocapitalize, autocomplete, autocorrect, spellcheck, inputmode and enterkeyhint.

The first four default to off, which is what a typeahead wants — the field matches the literal string you type against its options, so a keyboard that rewrites or capitalizes your input makes it search for something you did not ask for. Turn any of them back on if your field is prose rather than an identifier.

<ahi-combobox label="Client" autocorrect="on" autocapitalize="sentences"></ahi-combobox>

        
  
        
      

Use inputmode to raise the right keyboard, and enterkeyhint to label its Enter key:

<ahi-combobox label="Account number" inputmode="numeric" enterkeyhint="search"></ahi-combobox>

        
  
        
      

Best practices

1. Use clear, descriptive labels - Always provide a label that clearly describes what the user is selecting
2. Add help text for complex options - If the selection requires context, use the help-text attribute
3. Enable clearable for optional fields - Use clearable attribute to allow users to deselect
4. Consider list size - For very large lists (100+ items), use lazy with the ahi-search-change event, and set total-results so a capped list does not look complete
5. Test keyboard navigation - Ensure all interactions work with keyboard only
6. Provide meaningful placeholders - Use placeholders like “Type to search…” to indicate searchability

Importing

<script type="module" src="/path/to/azalea-kit-ui/dist/components/combobox/combobox.js"></script>
        
  
        
      

import '@azaleahealth/azalea-kit-ui/dist/components/combobox/combobox.js';
        
  
        
      

Slots

Learn more about using slots.

Properties

Learn more about properties and attributes.

Events

Learn more about events.

Methods

Learn more about methods.

CSS Parts

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

• <ahi-icon>
• <ahi-icon-button>
• <ahi-popup>
• <ahi-spinner>
• <ahi-tag>