React Dropdown List

The React Dropdown List component is a user interface element that allows users to select a single option from a list of predefined options. It typically appears as a collapsible list anchored to an input or trigger element. This component is commonly used for selecting categories, filtering data, or guiding users through a sequence of options.

Getting started

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

Installing Syncfusion® React packages

To use the React Dropdown List 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 Dropdown List 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-dropdowns/styles/material.css'

Adding Dropdown List component

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

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

Add the Dropdown List component in application as shown in below code example.

        import { DropDownList } from '@syncfusion/react-dropdowns';
        import './app.css';
        
        export default function App() {
          const sportsData = [
            { Id: 'game1', Game: 'Badminton' },
            { Id: 'game2', Game: 'Football' },
            { Id: 'game3', Game: 'Tennis' }
          ];
        
          const fields = { text: 'Game', value: 'Id' };
        
          return (
            <div className="component-section dropdownlist-container">
              <DropDownList
                dataSource={sportsData}
                fields={fields}
                placeholder="Select a game"
                style={{ width: '300px' }}
              />
            </div>
          );
        }

Run the project

To run the project, use the following command:

npm run dev

The following example demonstrates a basic Dropdown List with a simple list. Click the Dropdown List element and select an item from the options list.

Primitive data binding

The Dropdown List 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 Dropdown List 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.

Grouping

Grouping feature enables you to organize dropdown items into logical categories using the groupBy property. This functionality is particularly valuable when managing large datasets, as it arranges related items together, significantly improving user navigation and item discoverability.

Filtering

The Dropdown List component makes finding items simple with its built-in filtering feature. When you turn on filtering by setting filterable to true, users can quickly narrow down choices by typing in the search box. The list automatically updates to show only matching items as you type, making it easy to find what you are looking for in large lists. To control input performance, use debounceDelay to wait the specified milliseconds before applying the filter. You can also choose how matches are evaluated using filterType, which determines whether filtering uses StartsWith, Contains, or EndsWith.

Diacritics Filtering

The Dropdown List 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 Dropdown List 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 RemoteData

The Dropdown List 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.

Cascading Dropdowns

The Dropdown List component supports cascading dropdown functionality where selecting an option in one dropdown affects the available options in subsequent dropdowns.

In this example:

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

Custom Rendering

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

Item template

The Dropdown List component allows you to customize the appearance of each item in the Dropdown List 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 Dropdown List 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.

No Records template

The Dropdown List 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."

Header template

The Dropdown List 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 dropdown list items. The headerTemplate function returns the customized title content, such as "Suggested contacts", which appears as the header of the dropdown.

Footer template

The Dropdown List 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 dropdown 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 Dropdown List 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 dropdown list. This customized value is then displayed in the input field, providing a richer and more informative selection experience.

Variants

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

Appearance

The Dropdown List 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 Dropdown List 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 Dropdown List:

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.

ReadOnly

The Dropdown List 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 Dropdown List in read-only mode:

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

Float Label

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

Disabled items

The Dropdown List 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 Dropdown List 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 Dropdown List 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 membership form with validation for required dropdown selections:

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 Dropdown List component follows accessibility guidelines and standards, including ADA, Section 508, WCAG 2.2 standards, and WCAG roles that are commonly used to evaluate accessibility.

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

Dropdown input

Popup listbox

Keyboard interaction

Use the following keyboard shortcuts to navigate and select items in the Dropdown List. The behavior is split into two parts:

• When focus is on the input (popup closed)
• When the popup list is open

When focus is on the Dropdown List input (popup closed)

When the popup list is open