Dropdown List API - Syncfusion® React

DropDownList lets users choose a single option from a list. It works with local or remote data sources, supports custom item, group, header, footer, and value templates, offers built-in filtering with debounce and case/accent handling, enables grouping and sorting, and keyboard navigation.

Usage

To import and use the Dropdown List component in your application, use the following code snippet:

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

export default function App() {
const data = [
  { text: "Apple", value: "apple" },
  { text: "Banana", value: "banana" },
  { text: "Cherry", value: "cherry" }
];
return (
  <DropDownList
    id="fruits"
    dataSource={data}
    fields={{ text: "text", value: "value" }}
    placeholder="Select a fruit" />
);
}

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

export default function App() {
const data = [
  { text: "Apple", value: "apple" },
  { text: "Banana", value: "banana" },
  { text: "Cherry", value: "cherry" }
];
return (
  <DropDownList
    id="fruits"
    dataSource={data}
    fields={{ text: "text", value: "value" }}
    placeholder="Select a fruit" />
);
}

Demos

Explore the demos of the React Dropdown List component. Refer to this page.

Props

The following table outlines the props for the Dropdown List component:

Name	Type	Default	Description
allowObjectBinding	boolean	false	Specifies whether to allow binding of complex objects as values instead of primitive values. When enabled, the entire object can be accessed in events.
clearButton	boolean \| node	false	Specifies whether to show a clear button in the DropDownList component. When enabled, a clear icon appears when a value is selected, allowing users to clear the selection.
dataSource	{ [key: string]: unknown }[] \| DataManager \| string[] \| number[] \| boolean[] \| unknown	[ ]	Specifies the data source for populating the dropdown items. Accepts various data formats including array of objects, primitive arrays, or DataManager.
debounceDelay	number	0	Specifies the debounce delay (in milliseconds) for filtering input.
defaultValue	number \| string \| boolean \| object \| null	-	Specifies the default value of the DropDownList. Similar to the native select HTML element.
dropdownIcon	node	-	Specifies a custom SVG icon to be rendered in the Dropdown List input element.
fields	FieldSettingsModel	{ text: 'text', value: 'value', disabled: 'disabled', groupBy: 'groupBy' }	Specifies the mapping fields for text and value properties in the data source objects. Helps in binding complex data structures to the dropdown.
filterPlaceholder	string	-	Specifies the placeholder text to be shown in the filter bar of the DropDownList.
filterType	FilterType	'StartsWith'	Specifies the type of filtering to be applied.
filterable	boolean	false	Specifies whether filtering should be allowed in the DropDownList.
footerTemplate	node	-	Specifies a custom template for rendering the footer section of the dropdown popup, enabling additional content below the item list.
groupTemplate	Function \| node	-	Specifies a custom template for rendering group header sections when items are categorized into groups in the dropdown list.
headerTemplate	node	-	Specifies a custom template for rendering the header section of the dropdown popup, enabling additional content above the item list.
ignoreAccent	boolean	false	Specifies whether to ignore diacritics while filtering or selecting items.
ignoreCase	boolean	true	Specifies whether the DropDownList should ignore case while filtering or selecting items.
inputProps	React.InputHTMLAttributes<HTMLInputElement>	-	Specifies additional HTML attributes to apply to the underlying input element. Values provided here can override default aria-* attributes set by the component.
itemTemplate	Function \| node	-	Specifies a custom template for rendering each item in the dropdown list, allowing for customized appearance of list items.
labelMode	LabelMode	LabelMode.Never	Specifies the behavior of the floating label associated with the DropDownList input. Determines when and how the label appears.
loading	boolean	false	Specifies whether the component is in loading state. When true, a spinner icon replaces the default caret icon.
noRecordsTemplate	node	'No Records Found'	Specifies a custom template for the message displayed when no items match the search criteria or when the data source is empty.
onErrorTemplate	node	-	Specifies a custom template to render when an error occurs in the Dropdown List.
open	boolean	false	Specifies whether the dropdown popup is open or closed.
placeholder	string	-	Specifies the placeholder text that appears in the DropDownList when no item is selected.
popupSettings	PopupSettings	{ width: '100%', height: '300px', zIndex: 1000 }	Specifies popup-specific settings such as width, height, position, offsets, collision, z-index, and auto-reposition behavior.
query	Query	-	Specifies the query to retrieve data from the data source. This is useful when working with DataManager for complex data operations.
required	boolean	-	Specifies whether the component is a required field in a form. When set to true, the component will be marked as required.
size	Size	Size.Medium	Specifies the size style of the dropdown list. Options include 'Small', 'Medium' and 'Large'.
sortOrder	SortOrder	SortOrder.None	Specifies the sort order for the DropDownList items.
valid	boolean	-	Specifies whether to override the validity state of the component. If valid is set, the required property will be ignored.
validationMessage	string	-	Specifies the form error message of the component.
validityStyles	boolean	true	Specifies whether to apply visual representation of the invalid state of the component. If set to false, no visual representation of the invalid state of the component will be applied.
value	number \| string \| boolean \| object \| null	-	Specifies the value to be selected in the DropDownList component. This can be a primitive value or an object based on the configured data binding.
valueTemplate	Function \| node	-	Specifies a custom template for rendering the selected value in the input element, allowing for customized appearance of the selection.
variant	Variant	Variant.Standard	Specifies the variant style of the dropdown list. Options include 'Outlined', 'Filled', and 'Standard'.

Events

The following table outlines the events for the Dropdown List component:

Name	Type	Description
onChange	(event: ChangeEvent) => void	Specifies an event that triggers when the selected value of the DropDownList changes, providing details about the new and previous values.
onClose	(event: PopupEvent) => void	Specifies an event that triggers when the dropdown popup closes, allowing for custom actions to be performed at that moment.
onDataLoad	(event: DataLoadEvent) => void	Specifies an event that triggers after data is fetched successfully.
onDataRequest	(event: DataRequestEvent) => void	Specifies an event that triggers before data is fetched.
onError	(event: Error) => void	Specifies an event that triggers when data fetching fails
onFilter	(event: FilterEvent) => void	Specifies an event that triggers on typing a character in the filter bar when the filtering is enabled.
onOpen	(event: PopupEvent) => void	Specifies an event that triggers when the dropdown popup opens, allowing for custom actions to be performed at that moment.
onSelect	(event: SelectEvent) => void	Specifies an event that triggers when an item in the dropdown list is selected, providing details about the selected item.

Dropdown List Component

Usage

Demos

Props

Events