React Autocomplete

The React Autocomplete component is an intelligent text input field with dynamic suggestions that appear as users type. It allows users to quickly find and select from a list of suggestions, with support for filtering, grouping, custom values, and more. It is commonly used for efficient data entry where providing contextual suggestions improves user experience and data accuracy.

Getting Started with the React Autocomplete

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 Autocomplete component to the project.

Installing Syncfusion® React packages

To use the React Autocomplete 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 Autocomplete 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 Autocomplete component

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

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

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

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

const fields = { value: 'id', text: 'name' };

export default function App() {
  return (
    <div className="component-section sf-display-flex flex-direction-column mid-gap">
      <Autocomplete
        dataSource={dailyHabits}
        fields={fields}
        placeholder="Choose a daily habit (e.g. Meditate)"
        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 Autocomplete with a simple list. Start typing to see suggestions, and select an item from the list.

Primitive data binding

The Autocomplete 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 Autocomplete 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 Autocomplete 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 Autocomplete 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 Autocomplete 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 autocomplete, providing flexibility beyond predefined options.

Minimum length

The Autocomplete component supports the minLength property which specifies the minimum number of characters required before suggestions appear. This helps reduce the number of results shown for very short search queries and improves performance when dealing with large datasets.

Maximum suggestions

The Autocomplete component supports the maxSuggestions property which limits the maximum number of suggestions displayed in the suggestions. This is useful for controlling the size of the dropdown and providing a more focused list of top matching results to the user.

Grouping

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

Diacritics filtering

The Autocomplete 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.

Resizable popup

The Autocomplete 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 Autocomplete 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 types (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 Autocomplete 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 Autocomplete.
• Custom fetch: Retrieve arrays using fetch() (or another client fetch), assign the returned array to the Autocomplete's dataSource.

Lazy loading data

Lazy loading fetches data as the user types 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 Autocomplete

The Autocomplete component supports cascading autocomplete functionality where input in one autocomplete affects the available suggestions in subsequent autocomplete components.

In this example:

• First, start typing a country name in the first autocomplete.
• Then, type a region name in the second autocomplete (suggestions depend on the selected country)
• Finally, type a city name in the third autocomplete (suggestions depend on the selected region)

Custom rendering

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

Item template

The Autocomplete component allows you to customize the appearance of each item in the Autocomplete 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 Autocomplete 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 Autocomplete 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 autocomplete list items. The headerTemplate function returns the customized title content, such as "Suggested contacts", which appears as the header of the autocomplete.

Footer template

The Autocomplete 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 autocomplete list items. The footerTemplate function returns an "Add contacts" element, which is rendered below the list and can be customized as needed.

Value template

The Autocomplete component allows you to customize the appearance of the entered 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 custom formatted content when a value is selected from the autocomplete list. This customized value is then displayed in the input field, providing a richer and more informative input experience.

No records template

The Autocomplete 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 matches found."

Variants

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

Appearance

The Autocomplete 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 Autocomplete 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 Autocomplete:

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 Autocomplete 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 an Autocomplete in read-only mode:

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

Float label

The Autocomplete 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 Autocomplete 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 Autocomplete 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 autocomplete to inform users about the issue and guide them to correct it.

Disabled items

The Autocomplete 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 Autocomplete component supports both controlled and uncontrolled modes. In controlled mode, the input value is managed externally using the value property. Any change in the value must be handled through onChange callback event. In 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 Autocomplete 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 a contact form with validation for required autocomplete entries:

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

Accessibility

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

The accessibility compliance for the Autocomplete 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 Autocomplete follows the WAI-ARIA patterns to meet accessibility requirements. The following ARIA attributes are used:

Autocomplete input

Popup listbox

Keyboard interaction

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

When focus is on the Autocomplete input (popup closed)

When the popup list is open