React ComboBox

The React ComboBox component is an editable input with an associated list of suggestions. Users can either pick from the suggestion list or type to filter and, when enabled, commit custom values. It is commonly used for flexible selection inputs where both free-form text and guided selection are valuable.

Getting Started with the React ComboBox

To create a new Vite project, refer to the Vite documentation. Once that Vite project is ready to run with default settings, let's add the React ComboBox component to the project.

Installing Syncfusion® React packages

To use the React ComboBox component in this project, the @syncfusion/react-dropdowns package needs to be installed using the following command:

npm install @syncfusion/react-dropdowns

Adding CSS reference

In this article, the Material theme is applied using CSS styles, which are available in installed packages. The necessary Material CSS styles for the ComboBox component and its dependents were imported into the src/App.css file.

@import '../node_modules/@syncfusion/react-base/styles/material.css';
@import '../node_modules/@syncfusion/react-lists/styles/material.css';
@import '../node_modules/@syncfusion/react-inputs/styles/material.css';
@import '../node_modules/@syncfusion/react-popups/styles/material.css';
@import '../node_modules/@syncfusion/react-dropdowns/styles/material.css'

Adding ComboBox component

To include the ComboBox component in your application, import the ComboBox from the @syncfusion/react-dropdowns package in App.tsx.

import { ComboBox } from "@syncfusion/react-dropdowns";

Add the ComboBox component in application as shown in below code example.

'use client';
import { ComboBox } from '@syncfusion/react-dropdowns';
import { ticketData } from './datasource';
import './app.css';

export default function App() {
  const fields = { text: 'text', value: 'value' };

  return (
    <div className="component-section">
      <ComboBox
        placeholder="Choose a ticket category (e.g. Billing)"
        fields={fields}
        dataSource={ticketData}
        clearButton
        style={{ width: 300 }}
      />
    </div>
  );
}

Run the project

To run the project, use the following command:

npm run dev

The following example demonstrates a basic ComboBox with a simple list. Click the ComboBox and select an item, or type to search.

Primitive data binding

The ComboBox component can be bound to an array of primitive values, such as strings or numbers. This is useful for scenarios where the data is simple and does not require a complex data structure.

Remote data binding

The ComboBox component can be bound to remote data sources like APIs through the DataManager. The dataSource property establishes the connection to external data, while the query property filters and customizes what data is retrieved from the server. This approach is perfect for applications that need to display server-side data without loading everything at once.

Autofill

The ComboBox component supports autofill functionality that automatically completes the input field with the first matching suggestion as the user types. The auto-filled text appears highlighted, allowing users to accept it by pressing Enter or continue typing further.

Auto highlight

The ComboBox component provides auto highlight functionality that highlights the matching search text within suggestions. This feature improves visibility and helps users quickly identify which part of the suggestion matches their search query, especially useful when filtering through large datasets.

Custom value

The ComboBox component supports custom value functionality that allows users to enter and commit custom text values that are not present in the suggestion list. By pressing Enter, users can add custom values to the combobox, providing flexibility beyond predefined options.

Grouping

Grouping enables you to organize suggestions into logical categories using the groupBy field mapping. This improves navigation and discoverability in large datasets.

Filtering

The ComboBox offers built-in filtering. Set filterable to true so users can narrow choices by typing. Tuning debounceDelay helps balance responsiveness and performance.

Diacritics filtering

The ComboBox component supports diacritics filtering which will ignore the diacritics and makes it easier to filter the results in international characters lists when the ignoreAccent is enabled.

Grouping with filtering

The ComboBox component supports grouping along with filtering, allowing users to easily navigate and select items from categorized lists. When filtering is enabled, the component dynamically narrows down the grouped items based on the user's input, enhancing usability especially in large datasets.

Filtering with remote data

The ComboBox component supports filtering with remote data sources, enabling efficient handling of large datasets. As users type into the input field, the component fetches matching results from a remote server, ensuring performance and responsiveness even with extensive data collections.

Resizable popup

The ComboBox component supports a resizable dropdown popup that users can resize for better visibility of long lists and descriptions. By dragging the bottom-right corner of the popup, users can expand or adjust the dropdown to fit their needs.

Virtualization

Virtualization keeps the ComboBox fast with very large datasets by creating DOM nodes only for visible items; demos show common patterns for local and remote data and how to tune rendering and fetch behavior.

• itemSize: Fixed row height in pixels — set to the actual rendered height so scroll math is accurate.
• pageSize: Items per fetch/render batch — larger values mean fewer requests but higher memory/initial cost.
• overscanCount: Extra items rendered above/below the viewport to prevent gaps during fast scrolling and improve smoothness.
• showSkeleton: When true, render lightweight placeholder rows while remote data is loading to improve perceived performance.
• scrollMode: FetchViewPort requests pages incrementally as the user scrolls (server must handle paging/filtering/grouping); FetchAll expects the full dataset and renders it up front.

This demo contains plain, grouped and filterable examples.

Remote data

Virtualize the ComboBox when loading data from a server to improve performance.

• Built-in DataManager: Configure DataManager with the remote URL and adapter; it will handle requests and paging for the ComboBox.
• Custom fetch: Retrieve arrays using fetch() (or another client fetch), assign the returned array to the ComboBox's dataSource.

Lazy loading data

Lazy loading fetches data as the user scrolls to minimize initial load time and memory usage; use either built-in DataManager virtualization or a custom fetch depending on your backend and control needs.

• Built-in DataManager: set virtualization: { scrollMode: ScrollMode.FetchViewPort } so DataManager requests pages as the viewport changes; filtering can be forwarded, but grouping/sorting must be done server-side.
• Custom fetch: load the first page into dataSource, use onScroll (with a threshold) to detect near-bottom, fetch the next page, and concat results into dataSource. Implement grouping and sorting on the server.

Cascading ComboBoxes

The ComboBox component supports cascading combobox functionality where selecting an option in one combobox affects the available options in subsequent comboboxes.

In this example:

• First, select a country from the first combobox.
• Then, select a region from the second combobox (options depend on the selected country)
• Finally, select a city from the third combobox (options depend on the selected region)

Custom rendering

The ComboBox component supports various options to customize the appearance and structure of the dropdown elements.

Item template

The ComboBox component allows you to customize the appearance of each item in the Combo Box using the itemTemplate property. This is useful for displaying additional information or styling items in a specific way. The itemTemplate function receives each item's data and returns HTML elements (such as avatar initials, name, and status) with the required class names defined in the style file, enabling simple and flexible rendering of each list item.

Group template

The ComboBox component allows you to customize the appearance of group headers using the groupTemplate property. This is useful for displaying additional information or styling group headers in a specific way. The groupTemplate function receives the items' data, reads the status, calculates a summary (such as item count and total budget with currency formatting), and returns an HTML block with class names. These class names are styled in the style file and can be easily customized as per requirements.

Header template

The ComboBox component allows you to add a custom header at the top of the popup list using the headerTemplate property. This is useful for displaying titles, helper text, or other contextual information above the combobox list items. The headerTemplate function returns the customized title content, such as "Suggested contacts", which appears as the header of the combobox.

Footer template

The ComboBox component allows you to add a custom footer at the bottom of the popup list using the footerTemplate property. This is useful for displaying additional information, links, or actions like "Add new" or "View all" below the combobox list items. The footerTemplate function returns an "Add products" element, which is rendered below the list and can be customized as needed.

Value template

The ComboBox component allows you to customize the appearance of the selected value using the valueTemplate property. This is useful for displaying additional information such as an avatar, secondary text, or applying custom formatting and styles to the selected item. The valueTemplate function returns the organization symbol, organization name, and the stock price when an item is selected from the combobox list. This customized value is then displayed in the input field, providing a richer and more informative selection experience.

No records template

The ComboBox component allows you to customize the message displayed using the noRecordsTemplate property when no data is available or when filtering returns no results. This enhances the user experience by providing a more informative or branded message instead of a generic "No records found."

Variants

The ComboBox component enhances user interaction through its three distinct visual variants: Standard, Outlined and Filled.

Appearance

The ComboBox component provides various options to customize its appearance, including the ability to disable specific items in the dropdown menu. This feature is useful when certain options should be visible but not selectable in particular contexts.

Disabled

The ComboBox component can be completely disabled by setting the disabled property to true. When disabled, the component becomes non-interactive and visually indicates its disabled state to the user. The example below demonstrates a fully disabled Combo Box:

Note: This is different from disabling individual items within the dropdown (which is shown in the "Disabled items" section). The disabled property affects the entire component.

Read only

The ComboBox component can be set to a read-only state by setting the readOnly property to true. In this state, the component displays its current value but doesn't allow any interaction with the dropdown functionality. The example below demonstrates a Combo Box in read-only mode:

Note: The read-only state differs from the disabled state. While both prevent changes to the selection, a read-only combobox maintains its visual appearance and can receive focus, whereas a disabled combobox appears visually inactive and cannot receive focus.

Float label

The ComboBox component supports different label display modes through the labelMode property. This property controls how the label or placeholder text appears in relation to the input field.

Available label mode options:

• "Never": The label will never float in the input when the placeholder is available.
• "Always": The floating label will always float above the input.
• "Auto": The floating label will float above the input after focusing or entering a value in the input.

The following sample illustrates how the Combo Box behaves with different label mode settings, allowing you to see how each option affects the appearance and interaction of labels relative to the input field.

Invalid

The ComboBox component can be styled to indicate an invalid state using the "sf-error" class. This is particularly useful in form validation scenarios where user input is required or incorrect. A descriptive error message can be displayed below or near the combobox to inform users about the issue and guide them to correct it.

Disabled items

The ComboBox component allows you to disable specific items in the dropdown lists, preventing users from selecting them. This is useful when certain options should be visible but not selectable in particular contexts.

To disable items, include a boolean property in your data objects (like disabled: true) and map it to the disabled field in the fields configuration object.

Controlled vs uncontrolled

The ComboBox component supports both controlled and uncontrolled modes. In controlled mode, selected value is managed externally using the value property. Any change in selection must be handled through onChange callback event. while uncontrolled mode, the component manages its own state internally. Setting an initial value using the defaultValue property, and the component handles further updates automatically.

Forms support

The Combo Box component integrates seamlessly with forms, providing built-in validation capabilities. The component supports form validation through properties like validityStyles, valid, and validationMessage. The example below demonstrates an event registration form with validation for participant name and ticket tier selection:

Using the validityStyles property (set to true by default), you can control whether validation styling is applied. The valid property determines if the current selection passes validation, while validationMessage allows you to provide contextual error messages to guide users.

Accessibility

The ComboBox follows accessibility guidelines and standards, including ADA, Section 508, WCAG 2.2 standards, and WCAG roles.

The accessibility compliance for the ComboBox component is outlined below.

- All features of the component meet the requirement.

- Some features of the component do not meet the requirement.

- The component does not meet the requirement.

WAI-ARIA attributes

The ComboBox follows the WAI-ARIA patterns to meet accessibility requirements. The following ARIA attributes are used:

Combobox input

Popup listbox

Keyboard interaction

Use the following keyboard shortcuts to navigate and select items in the ComboBox.

When focus is on the ComboBox input (popup closed)

When the popup list is open